Once your new ETM feature is ready, it's important to write documentation so that visitors understand how to use it, and fellow modelers and developers can see how it works.
Documentation is split into three sections:
For users. These are aimed at those who visit the ETM, and should explain how to use the website, providing details on how features work from the perspective of a visitor. These documents are located in docs/main.
For contributors. These docs are aimed at Quintel employees as well as outside modelers and developers who may wish to contribute. This sections should contain descriptions of how features are implemented and guides for using them in ETSource. These documents can be found at docs/contrib.
All documentation is written in Markdown. For an overview of supported features, see the Docusaurus docs. Markdown file names should be all lowercase with spaces replaced with dashes.
Titles and YAML
The start of your document must contain YAML front-matter with at least a title attribute:
title: My first document!
Document contents start here. No need to add the page title; Docusaurus
will use the above `title` attribute.
If your document title is quite long and will not fit neatly on the sidebar, consider adding a shorter label to be used only on the sidebar:
title: My second document, whose title is clearly too long
sidebar_label: Second document
Linking to other documents
Use Markdown links to link to another document. These should be relative to the current document: include the ".md" suffix as this will allow the documents to be navigated on GitHub. See Docusaurus → Referencing other documents.
[My link text](../main/cost-calculations.md)
Linking to headers and sections
To link to a section in the same document, you must find the header you wish to link to, then convert all characters to lowercase and swap spaces for dashes. The string is then prefixed with a "
[My link text](#electricity-production)
To link to a section in another document, start with the link to the other document then add the header link:
[My link text](../cost-calculations.md#electricity-production)
Caution when changing headers!
As section IDs are automatically generated from the header text, changing the title of a section in a Markdown document will break any existing links to that header. Be sure to search for the outdated references and update them as necessary:
git grep "my-old-title"
![My image alt. text](/img/docs/total_capacity.jpg)
Please compress images with a tool like ImageOptim prior to committing.
Adding to the sidebar
Documents do not automatically appear in the sidebar. Instead, they must be added to the sidebar.js in the project root. This file contains the definitions for three sidebars:
mainSidebarused by the "For Users" section.
contribSidebarused by the "For Contributors" section.
apiSidebarused by the "API Reference" section.
Find the category most appropriate for your document (or add a new one), then add the path of the file minus the "docs/" prefix and ".md" suffix to the
items list. For example, if adding a document located at docs/main/new-costs.md, which you wish to appear below the "Cost calculations" document, add the following line to the "Costs" category:
All documents are indexed by Algolia DocSearch once per day; you do not need to do anything. It may take up to 24 hours for your changes to be reflected in the index.
Pushing your changes
Editing documents does not require you to install anything. You may edit and push changes to the Markdown files, with the website being built and deployed automatically when pushed to the