> For the complete documentation index, see [llms.txt](https://docs.boston.gov/digital/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.boston.gov/digital/getting-started/using-gitbook.md).

# Using GitBook

Tips on how to use GitBook for documentation.

{% hint style="info" %}
See GitBook’s documentation at <https://docs.gitbook.com/content-editing>.
{% endhint %}

## 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](https://docs.gitbook.com/integrations/github/faq#nothing-happens-on-gitbook-after-adding-a-new-file-to-my-repository) for it to appear in gitbooks.
