-
Notifications
You must be signed in to change notification settings - Fork 1
Docusaurus documentation
mAtches uses Docusaurus for rendering documentation (https://docusaurus.io/). Note that we use v2 of Docusaurus.
Docusaurus uses markdown, configuration files, static resources, and some limited React-based components to render documentation. mAtches uses GitHub Pages for deploying the documentation built with Docusaurus. All documents/resources for our Docusaurus-built site can be found within the documentation directory of the main branch.
In general, you can refer to Docusaurus documentation (https://docusaurus.io/docs/2.0.0-alpha.72/), but the following notes below explain the existing implementation that mAtches is using.
General config (e.g. website title, baseurl, etc.,) can be edited in the config file: https://github.com/pepfar-datim/mAtches/blob/a119bee01f40a5c889f9096a32138f74f8bc796a/documentation/docusaurus.config. Note that the baseurl should be /mAtches/ (with trailing slash) for deployment on GitHub pages for mAtches repo. This will work running locally, but for testing static version of the site after build with yarn serve, you may need to temporarily set the baseurl to /.
The Navigation Bar is controlled from within Docusaurus config: https://github.com/pepfar-datim/mAtches/blob/a119bee01f40a5c889f9096a32138f74f8bc796a/documentation/docusaurus.config.js#L18-L66. Note that href can be a document that will be generated by Docusaurus (should be the first document that appears in the sidebar). Note that the link will only exist for the exact path, e.g. if document is titled 'dogs' and in a directory 'dachshund' then the link will have to be to '/dogs/dachshund' as '/dogs' alone will return 404 error.
Main page is written in React: https://github.com/pepfar-datim/mAtches/blob/master/documentation/src/pages/index.js. This can be modified if desired (currently using the default layout). mAtches currently uses the classic layout and the navigation bars are loaded with that component (). Styling can be done with https://github.com/pepfar-datim/mAtches/blob/master/documentation/src/css/custom.css (example of styling is redefining of colors to match mAtches color scheme and frontPage-button styling)
Sidebars for categories within documentation can be configured here: https://github.com/pepfar-datim/mAtches/blob/master/documentation/sidebars.js. This allows you to organize documents within subcategories that then present for navigation in the sidebar.
To add an individual document, you can just add a markdown file under docs directory. ID will be automatically generated if nothing is provided, but you can also add it explicitly. title and sidebar_label should also be added. The document will be rendered in HTML during build step.
You can also create individual pages here: https://github.com/pepfar-datim/mAtches/tree/master/documentation/src/pages. A page can be created in React/js or as a document. An example page is the docs.md.
You need to set up Docusaurus locally in order to test, build the documentation site. The README in documentation directory has the standard instructions (i.e. you need to run yarn install or npm install).
To deploy content from Docusaurus, while in the documentation directory, run yarn build and then GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy (assuming that you are accessing git with SSH).
When Docusaurus completes build a static version of the documentation is generated and committed to gh-pages branch of mAtches repo. This static version can then be deployed using GitHub pages if a user with admin access to the repo enables GitHub pages (see https://github.com/pepfar-datim/mAtches/settings/pages ) and selects gh-pages as the branch to deploy from.