Using GitBook

Tips on how to use GitBook for documentation.

See GitBook’s documentation at https://docs.gitbook.com/content-editing.

Creating new pages

“Guide” or “Standards and best practices”?

If you’re documenting how to perform a task, organize it as a Guide. Most of the docs in our GitBook space will be Guides. (e.g. How do I start a new project?)

“Standards and best practices” is where to document things like What files need to be included in every project? What library should I be using?

Make sure you’re in editing mode

In order to add new pages, you need to switch into editing mode first. It’s easy to forget!

Use H1 and H2 headings to organize your content

GitBook will automatically create a list of hyperlinks from H1s and H2s as the page “contents” block in the upper-right of the page. Although it isn’t semantically correct, use H1s for all section titles within a page, and H2s for subheadings.

General tips and quirks

Moving in and out of editing mode

When you are in editing mode, any changes you make will be autosaved as one draft: you can click through and edit multiple pages without needing to save before leaving a page. When you’ve finished, make sure to save the draft! Note that the “cancel” button will discard all changes you’ve made, not just the page you are currently on. Your changes will not be live until you merge in your draft.

Adding a file to gitbooks

If you add a new file in github, then you must also add it to the summary for it to appear in gitbooks.