- # Getting started
- # Adding pages
- # Collections
- # Templates & Partials
- # Styles & Assets
- # Variables
- # TypeDoc
- # Deployment
- # Config
- # Google Analytics
- # Travis CI
- # Plugins
Zeroth comes with documentation generation tools out of the box, so all you need to do is start writing.
Under the hood of
@zerothstack/toolchain is the awesome tool Metalsmith which allows for the
automatic generation of static sites using simple markdown source files and handlebars templates.
Zeroth “eats it’s own dogfood” as such so this documentation is generated using the same tooling.
To start writing documentation, first start up the documentation watcher:
$ u [zeroth] Loaded 12 commands. Type 'help' to see available commands zeroth~$ doc watch [doc] Removing directory ./dist-docs [doc] Done. [metalsmith-watch] ✓ Live reload server started on port: 35729 [metalsmith-serve] serving /Users/zak/zeroth/zeroth/dist-docs at http://localhost:8080 [doc] Copying doc assets from toolchain [metalsmith-watch] ✔︎ Watching **/* [doc] [zeroth] Doc watcher started at https://localhost:8080 Run 'doc stop' to stop the watch server
Now all you need to do is open your browser to http://localhost:8080
Note that you can still run other commands within the zeroth console. To stop the watch server, just run
CTRL+C (twice) to close the entire console.
Pages can be easily added by just creating a new markdown document anywhere under the
./docs directory and putting some
yaml frontmatter meta information.
For example the frontmatter for this page is:
--- title: Documentation date: 2016-06-09 collection: guide collectionSort: 1 layout: guide.hbs ---
Collections are groups of pages, and can be used to generate listings or navigation automatically. By default, the zeroth toolchain processes three collections:
main- the top-level items that should appear in the navigation
guide- pages to go under the guide page
articles- all pages for the articles section
If you set the
collection: <type> attribute in the frontmatter of your page, it will be automatically added to their
respective listings or navigation sections
Note: you may need to restart the doc watcher when adding new files as it only does a rebuild of changed files, and listings sections or navigation items may depend on other items
The template defines which handlebars template is used to render the page. The toolchain provides a few defaults:
|guide.hbs||Creating guide pages||Contents section, pending display|
|post.hbs||News articles||Date information|
All templates can be overidden by just placing your template in the same location as the toolchain. See the template directory in the toolchain for the locations of the layouts/partials
Like templates & partials, you can add your own assets into the
Any file that matches the same name as the toolchain will override the default.
./package.json file content is available globally to handlebars templates at
Any additional variables that you would like to add can be defined by configuring the
meta object of
configureDocs() in the
To run the generator, execute
typedoc in the cli. This takes a while so we don’t run it on every watch. This is
automatically run on deployment of the documentation, so you usually don’t need to worry about it when writing docs.
The toolchain is configured to be able to automatically deploy to github pages on the gh-pages branch. If you want to deploy to a different destination see the configuration options below:
Configuration of the deployment is handled in the
By default, the documentation will deploy to the
gh-pages branch at your repositories
If you have different requirements, see the
ZerothProject.configureDeployment() section for configuration options.
You can add tracking with Google Analytics to your documentation by configuring the
meta.gaCode property of
configureDocs() in the
To automate deployment fully, you can use TravisCI to run the deployment process, however you will need to configure keys so that Travis can push the documentation into the target branch.
- Add the following to your
after_success: - npm run coveralls - eval "$(ssh-agent -s)" #start the ssh agent - chmod 600 .travis/deployment_key.pem - ssh-add .travis/deployment_key.pem
- Add your encrypted private key to .travis/deployment_key.pem.enc
- see https://docs.travis-ci.com/user/encrypting-files/#Automated-Encryption for more encryption instructions
Note that you MUST NOT commit your unencrypted private key directly into
The toolchain currently uses the following metalsmith plugins:
At this time adding new plugins is not configurable. If you’d like this capability, get in touch.