outline / outline

The fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.

A fast, collaborative, knowledge base for your team built using React and Node.js.
Try out Outline using our hosted version at www.getoutline.com.

This is the source code that runs Outline and all the associated services. If you want to use Outline then you don't need to run this code, we offer a hosted version of the app at getoutline.com. You can also find documentation on using Outline in our guide.

If you'd like to run your own copy of Outline or contribute to development then this is the place for you.

Installation

Please see the documentation for running your own copy of Outline in a production configuration.

If you have questions or improvements for the docs please create a thread in GitHub discussions.

Development

There is a short guide for setting up a development environment if you wish to contribute changes, fixes, and improvements to Outline.

Contributing

Outline is built and maintained by a small team – we'd love your help to fix bugs and add features!

Before submitting a pull request please discuss with the core team by creating or commenting in an issue on GitHub – we'd also love to hear from you in the discussions. This way we can ensure that an approach is agreed on before code is written. This will result in a much higher likelihood of your code being accepted.

If you’re looking for ways to get started, here's a list of ways to help us improve Outline:

• Translation into other languages
• Issues with good first issue label
• Performance improvements, both on server and frontend
• Developer happiness and documentation
• Bugs and other issues listed on GitHub

Architecture

If you're interested in contributing or learning more about the Outline codebase please refer to the architecture document first for a high level overview of how the application is put together.

Debugging

In development Outline outputs simple logging to the console, prefixed by categories. In production it outputs JSON logs, these can be easily parsed by your preferred log ingestion pipeline.

HTTP logging is disabled by default, but can be enabled by setting the DEBUG=http environment variable.

Tests

We aim to have sufficient test coverage for critical parts of the application and aren't aiming for 100% unit test coverage. All API endpoints and anything authentication related should be thoroughly tested.

To add new tests, write your tests with Jest and add a file with .test.js extension next to the tested code.

# To run all tests
make test

# To run backend tests in watch mode
make watch

Once the test database is created with make test you may individually run frontend and backend tests directly.

# To run backend tests
yarn test:server

# To run a specific backend test
yarn test:server myTestFile

# To run frontend tests
yarn test:app

Migrations

Sequelize is used to create and run migrations, for example:

yarn sequelize migration:generate --name my-migration
yarn sequelize db:migrate

Or to run migrations on test database:

yarn sequelize db:migrate --env test

Activity

License

Outline is BSL 1.1 licensed.

outline's Issues

Prevent overriding changes when editing simultaneously

Potential solutions:

• Lock editing to a user and make it visible for others (realtime indicator would be killer)
• Check parent revision when starting and ending editing to prevent overriding changes
• ???

Loading state is not aligned with document

I guess this got broken at some point, it's in the top left rather than aligned with where the document title will be.

Can't use multiple Slack teams right now

Currently just picks whichever the user used first and won't save multiple ones

Stores Refactor

@jorilallo you mentioned refactoring the stores the other day, I think this is a good idea and should also extend to the DocumentsStore.

If this lives at a global level we can build up a cache of documents as you are navigating around the wiki and have everything load quicker…

Creating a new api token shows undefined

Creating a new api token shows undefined in UI. I'm not sure what this string is supposed to be - a description? 😄

Create "New Collection" UI

Add breadcrumbs for a document

Right now only the collection name and document name are shown, not actually the path to the document so it's hard to figure out where the document is stored. Would also be useful in search results but we'll probably need to cache this in the document

New API endpoints

• Add documents.recent
• Add documents.starred
• Add sortBy to documents.list eg, order by recently updated

Document organization

Right now organization happens via drag&drop and is kind of unreliable. Maybe something similar to Dropbox Paper might be better

Hitting ESC in search should go back to where you were

Keep getting caught by this little UX issue.

Homepage / Visual Design

We need a homepage at the least, most of the other site content can come later if most of the core info is collapsed onto that page.

Link toolbar does not work when highlighting first word in a block

It seems the selection moves outside of the link

Create github organization

We should move this project and the CLI to a new github organization at our leisure but before open sourcing, atlaswiki maybe?

Allow new collection creation

Also create and issue for onboarding

Push updates to Slack

• Probably when you "publish"
• Where, global settings or in collection settings? But per collection notifications

Entering edit mode should focus document

Important that the blinking cursor is seen for clarity.

Restore "New Document" functionality

Remove root document from collection in favor of array

• Payments
  • Playbook
    • ACH
  • Doc
    • Subdoc

Record document views

This could just be a count on the document for the first version? It will help to surface documents that are potentially most useful / popular

Restore created / edited information when viewing document

This will also help to distinguish between read and editing mode

Delete collection UI

Billing flow

Probably the last thing before we release, but here's a tracking issue so we can think about how this should work / the flows involved etc

Document list endpoints are very slow

Looking at the query log we have a lot of work to do, now that I have a bunch of test documents it's become clear that the server side is performing an incredible amount of queries to generate a list of documents. Typical response times in the client are 2s+.

New dashboard

Could really use a new dashboard to navigate different collections. Also potentially interesting:

• Favorited
• Recently changed
• Recently viewed

Add `prettier` to format code

We can replace all the lines of eslint config with this one dependency that makes sure all code is formatted the same way automatically. It's awesome, once you have it you never look back.

Any qualms?

Favorites

Starring of favorite documents

Editor upgrade

We discussed trying out another editor for size, perhaps with the ability to switch between wysiwyg and markdown depending on ease / appearance.

• Basic integration
• Ensure clicking top and bottom areas focus and move cursor correctly
• Support Markdown code tags
• Forced heading as the first block type
• Fix up placeholder to look like a heading, and
• Add a floating toolbar
• Restore styling for all block types
• Add keyboard shortcuts for marks
• Fix lines collapsing on save / restore
• Restore keyboard shortcuts from codemirror
• Add link editing to floating toolbar
• Ensure document title has no formatting / can't be formatted
• Icons for toolbar
• Toolbar design / styling (good enough for now)
• Fix incorrect serialization of list items (netlify/slate-markdown-serializer#2)
• Support horizontal rule "---"
• Support ordered lists
• Allow header block styling from toolbar
• Add clickable heading anchors when readOnly
• Restore dragging of images to insert / upload of images to s3
• Fix up saving of pasted images
• Shortcuts for inline markdown, eg ** / ~~
• Add todo checkboxes like these
• Nested list > md results in flat list
• List editing, waiting on GitbookIO/slate-edit-list#45
• Prevent app keyboard shortcuts from triggering whilst in editor (glortho/react-keydown#51)
• Incorrectly warn of unsaved changes
• Make link editing more reliable
• Combine document edit / show views so that only using one rendering engine

Clear editor state when re-opening editor

Better URLs

E.g.

• Collections: /<collection slug>
• Documents: /<collection slug>/<parent-document-slug>/<document-slug>-<slug ID>

TODO:

• collection slugs (DB change)
• ensure that collection slugs wont' collide

Open questions:

• What happens if the collection name changes?

Favicon

New document creation

Server tests not running

Something is broken, the server jest config isn't being used in the latest version.

Periods in urls break everything

Document returns a 404 after using a period in the title. Looks like slugs get messed up

Templates

Just a little issue to keep track of ideas / implementation for this feature.

Import Markdown files

A way to import existing random Markdown files through the web UI would be great. It could be just in the settings, drag and drop, or something else?

I think most teams have at least some existing documentation in a repo or dropbox so it might be best to start with a generic importer before moving onto specific importers for different services?

Add toolbar item to create checklist

This belongs in the block toolbar

Subdomain or other way to view multiple Atlases

Currently user can only be logged into one Atlas at the time which makes it quite limited. Slack style might work better.

API documentation

@jorilallo you mentioned that you've written something up - perhaps in the production Atlas account?

Do we want to keep this in an Atlas? If so then we need a way to publicly view a collection or we could put it in the repo now that it will be open-sourced.

Editing documents

Sidebar should scroll, not squash

Navigating documents is slow

There seems to be a delay when clicking through documents or into / out of collection even when all data is loaded and available.

Document shows undefined - undefined in title while loading

New domain

Need to figure out a new one, preferably a dotcom but lets see what's available. Also open to switching the name if we can find a good match.

Predictable new document url

It's a little odd to me that the url for a new document is based on the one you were looking at, even if it's not a child... eg:

Can we make this a predictable url for a new document, maybe per collection?

Drafts

This would be killer but needs scoping. Probably should be in user's global state over individual collections. I imagine we could make this work very similarly to Medium's Save/Publish

Navigating between collections is slow

A did a bunch of work here (6425450) to fix this up for navigating documents however moving between collections is still waiting for an API request response when that can be made unnecessary.

parseTitle is too simplistic

Right now it's just grabbing the contents of the first line and hoping it's a Header. When importing files in particular this isn't enough - for example on a number of occassions I've ended up with image tags in the title name 😆

We should imbue this method with some more smarts - probably parse the markdown tree and get the text content of the first node.

Locking for collection's document structure changes

As collection documentStructure operations can't be performed with one DB call, we should implement locking for API calls that modify documentStructure field.

Restore prompt when leaving editor with unsaved changes

This was lost with the move to react-router 4, need to use the new Prompt component

Remark

I'd like to move our Markdown parsing / serialization to Remark. It's a mature library built ontop of a real AST instead of the hacked together mess that's in the current serializer. I'll write utils to convert between the Slate AST <> Unified AST which will bring a number of awesome benefits…

• We can use Remark to Slate > AST > Remark and the reverse for the editor
• We can render directly using Rehype on the client to render Markdown output with having to use the editor, for example for document previews and be confident that the output will be the same.
• On the backend we can use Rehype to Markdown > HTML if needed for API.
• Renewed confidence in parsing