Cumulus Docs Installation
Run a Local Server
DOCSEARCH_INDEX_NAME must be set for search to work. At the moment, search is only truly functional on prod because that is the only website we have registered to be indexed with DocSearch (see below on search).
git clone email@example.com:nasa/cumulus
npm run docs-install
npm run docs-serve
docs-build will build the documents into
docs-clear will clear the documents.
Fix any broken links reported by Docusaurus if you see the following messages during build.
[INFO] Docusaurus found broken links!
Exhaustive list of all broken links found:
Our project documentation is hosted on GitHub Pages. The resources published to this website are housed in
docs/ directory at the top of the Cumulus repository. Those resources primarily consist of markdown files and images.
We use the open-source static website generator Docusaurus to build html files from our markdown documentation, add some organization and navigation, and provide some other niceties in the final website (search, easy templating, etc.).
Add a New Page and Sidebars
Adding a new page should be as simple as writing some documentation in markdown, placing it under the correct directory in the
docs/ folder and adding some configuration values wrapped by
--- at the top of the file. There are many files that already have this header which can be used as reference.
id: doc-unique-id # unique id for this document. This must be unique across ALL documentation under docs/
title: Title Of Doc # Whatever title you feel like adding. This will show up as the index to this page on the sidebar.
To have the new page show up in a sidebar the designated
id must be added to a sidebar in the
website/sidebars.js file. Docusaurus has an in depth explanation of sidebars here.
We lean heavily on Docusaurus for versioning. Their suggestions and walk-through can be found here. Docusaurus v2 uses snapshot approach for documentation versioning. Every versioned docs does not depends on other version. It is worth noting that we would like the Documentation versions to match up directly with release versions. However, a new versioned docs can take up a lot of repo space and require maintenance, we suggest to update existing versioned docs for minor releases when there are no significant functionality changes. Cumulus versioning is explained in the Versioning Docs.
Search on our documentation site is taken care of by DocSearch. We have been provided with an
apiKey and an
indexName by DocSearch that we include in our
website/docusaurus.config.js file. The rest, indexing and actual searching, we leave to DocSearch. Our builds expect environment variables for these values to exist -
Add a new task
The tasks list in docs/tasks.md is generated from the list of task package in the task folder. Do not edit the docs/tasks.md file directly.
Editing the tasks.md header or template
Look at the
bin/tasks-header.md files to edit the output of the tasks build script.
For some diagrams included in the documentation, the raw source is included in the
docs/assets/raw directory to allow for easy updating in the future:
assets/raw/interfaces.drawio(generated using draw.io)
master branch is automatically built and deployed to
gh-pages branch. The
gh-pages branch is served by Github Pages. Do not make edits to the