This project is used to produce all forms of documentation for the service using Markdown and other repository friendly markup languages.
The documentation is created using the mm-docs documentation bundle.
View how compiled static site looks like on demo site or grab generated artifact. Check out pdf export of single demo page.
See entire docs as a single page and/or download it.
- Documentation in Markdown, HTML, PlantUML, MatJax
- Beautiful responsive design using the material theme
- Navigational bar, TOC, color themes, go-to-top, search and various rich presentation functionalities
- Custom includables that can be imported in any page: footer, header, abbreviations etc.
- Variables, Python macros and jinja templates
- Multilanguage support
- Keep documentation for multiple user groups in the same project and build only specific one
- Fast PDF export and single page documentation site
- Bad link checker for internal and external links
- Metainformation for every page - last git modification date, source file, authors, etc.
- GitLab/GitHub repository connection for editing within a browser
- Automated AppVeyor and Github actions build and deploy to GitHub pages using Ubuntu image
- Live reload during editing
- Cross platform for hosting and development with convenient optional PowerShell task system
- Docker installation.
- For Windows Desktop use:
cinst docker-desktop
- For Windows Desktop use:
- PowerShell (optional)
- Invoke-Build module
Within PowerShell use Invoke-Build
(ib):
Task | Description |
---|---|
Build |
Build static site |
Run |
Serve static site locally with live reload |
Stop |
Stop running container |
CheckLinks |
Check internal and external links |
ExportPdf |
Export PDF of entire site |
ExportHTML |
Export standalone HTML of the entire site |
ExportSite |
Export entire site archive for offline use |
Clean |
Remove generated data |
Otherwise, run appropriate docker commands:
export image=majkinetor/mm-docs
export aPort=8888
#build
docker run --rm -v $PWD:/docs8 $image mkdocs build
#serve
docker run --rm -v $PWD:/docs --name docs-$aPort --detach -p $aPort:$aPort $image mkdocs serve --dev-addr 0.0.0.0:$aPort
After building it, static site is available at source\site
directory and it can be served with any kind of web server.
- Add new markdown somewhere in the
source/docs
directory. - To be visible in navigation, add to
source/mkdocs.yml
nav
section, otherwise, the page is available via direct link - Add footer, header, abbreviations etc. in
source/inc
folder - Add python function and modules in
source/main.py
- Override specific mkdocs material theme partials in
source/overrides
- Configure PDF and single page stuff in
source/pdf
- Configure extra CSS in
docs/_extra/css
- To build only specific section (using
ib -aSection <sectionName>
), make sure you haveregex: []
underexclude
plugin. Because mkdocs builds all pages no matter if they are present in thenav
section or not, this plugin option is used to NOT build other sections.