The documentation is based on the Divio Documentation System. This system doesn't have one thing called documentation, it has four: tutorials, how-to guides, technical reference, and explanations.
Technical references are generated by Typedoc based one comments within the TypeScript files themselves using the TSDoc standard. You can also use TypeDoc Includes to pull these markdown files into the reference docs.
How-to, explanations, and tutorials reside as markdown files within documentation/. docs/ is the generated output for github pages and is ignored.
documentation
├── explanations
├── how-tos
└── tutorials
Create your new .md file in one of the folders mentioned above based upon your documentation type. The filename doesn't have to match the title of the doc but it should be somewhat descriptive.
Update the typedoc.js configuration file. The pluginPages object contains all of the configuration for embedding markdown in the generated docs.
pluginPages: {
source: './documentation/',
pages: [
{
title: 'How To',
children: [
{ title: 'Contribute to these docs', source: './how-to/contribute-to-docs.md' },
{ title: 'Create a config file', source: './how-to/create-a-config-file.md' },
{ title: 'Release', source: './how-to/create-a-config-file.md' },
],
},
],
},
Above you can see a page with just a title and no source for How To. This creates the How To section header and brings all the specified child documents under it.
To modify the reference documents you need to change the TSDoc comments in the actual typescript source files under src/.
/**
* Creates a file-reader function for fetching the contents of a config
* file at the provided path.
* @param absoluteFilePath absolute path to the configuration file
*/
When the tsdoc generator runs it will pull this comment into the reference docs for that particular module. In this example we have a function description and a parameter description. The param types and returns are generated from the function definition.
Generated using TypeDoc