Suite Documentation
The suite template carries the configuration files needed to easily launch a documentation web site for your new tools suite using a permanent, customized fork of the open source Jekyll theme Just the Docs, called just-the-docs-mdi.
Configure your suite’s basic information
Open and edit the following files, following the instructions in the comments to find specific lines you need to edit to match your needs:
- _config.yml
- overview.md
- LICENSE (adjust the license type, year, and licensee as needed)
- aws-mdi.md (specify the resources needed for a public server, if relevant)
- README.md (delete these developer instructions, if desired)
Activate your documentation web page on github.io
Activate your new documentation site for loading via github.io as follows:
- navigate to your new repository on GitHub
- click “Settings”
- click the “Pages” tab on the left
- edit the “Source” to be branch ‘main’ and folder ‘/root’
- click ‘Save’
After about a minute, your site will be live at the link indicated on Settings / Pages. It will track your repository to keep your site up to date whenever you push or merge changes into the ‘main’ branch.
Please note that this only works if your repository is public.
Write your documentation files
Finally, create documentation page files within any folder. The easy way is to create markdown files similar to the overview.md file you edited above. By placing these as README.md files into the appropriate folders in your file tree, users will be able to see them both on GitHub and in your documentation web site.
Just the Docs usage
Please see the Just the Docs documentation for guidance on how to use the Jekyll front matter at the top of each markdown file to create the nested menu items typical of MDI documentation sites. Examples here will get you going:
https://github.com/MiDataInt/mdi-documentation-template/tree/main/_docs
Additional folders for helping users with options and templates
Sometimes users just want to see the list of all available options. The options folder in your tool suite can be populated using the script in that folder with markdown summaries easily viewed on GitHub.
Other times, an example is worth 1,000 documentation words. The templates and logs folders can be similarly populated with job file templates and the output of those or other job files for users to compare to their own work.
See the folder contents for additional information.