-
Notifications
You must be signed in to change notification settings - Fork 1
Writing Pages
All pages are written using Markdown. If you're unfamiliar with Markdown syntax (or just need a handy reference), check out Markdown Guide.
Every page should start with an H1 tag followed by a paragraph tag that acts as a summary of the contents of the file. After that, a simply horizontal break (three consecutive hyphens) should be used before starting the content of the page.
# Installation
Learn how to get up and running with Nova 3.
---
Note: You should only use an H1 tag at the beginning of the document. All other major sub-sections within the page should be denoted by H2s.
You can (and should) use screenshots where it makes sense to illustrate something that's being written.
There is an images/docs/{version} folder where you can store your images for a page. Please make sure you're putting your images in a folder with the name of the page and then a filename that explains what the image is (i.e. upgrade-guide/options.png). In your page, you can then reference the image with Markdown:
Note: the leading slash is important otherwise the images will not appear on the live site correctly.
The documentation site creates an in-page table of contents for each page by identifying all of the H2 and H3 tags and displaying their content in a sidebar on the right-hand side and building links for quick and easy access. Since everything from H4 down isn't captured in the TOC, we want to avoid situations where we're nesting content too deeply inside a sub-section. There are situations where H4 tags make sense, but it's important to keep the TOC in mind. On long pages, users will rely on that TOC to be able to navigate through content quickly.
In some cases, Markdown may not provide the ability to do something we need. In those situations it is possible to drop down to raw HTML, but that should be using sparingly. We want to avoid situations where we have to copy/paste specific HTML code to use in a lot of different files.