Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/majkinetor/mm-docs-template
Template to use with mm-docs
https://github.com/majkinetor/mm-docs-template
documentation documentation-generator markdown mkdocs mm-docs plantuml
Last synced: about 2 months ago
JSON representation
Template to use with mm-docs
- Host: GitHub
- URL: https://github.com/majkinetor/mm-docs-template
- Owner: majkinetor
- Created: 2019-04-10T20:48:01.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-29T10:45:51.000Z (6 months ago)
- Last Synced: 2024-06-29T11:49:52.386Z (6 months ago)
- Topics: documentation, documentation-generator, markdown, mkdocs, mm-docs, plantuml
- Language: PowerShell
- Homepage:
- Size: 2.45 MB
- Stars: 8
- Watchers: 4
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# MM-DOCS Template
[](https://github.com/majkinetor/mm-docs-template/actions/workflows/mm-docs.yml)
[](#)
[](#)
[VIEW DEMO](https://majkinetor.github.io/mm-docs-template)
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](https://github.com/majkinetor/mm-docs) documentation bundle.
View how compiled static site looks like on [demo site](https://majkinetor.github.io/mm-docs-template) or grab generated [artifact](https://ci.appveyor.com/project/majkinetor/mm-docs-template/build/artifacts). Check out [pdf export](https://majkinetor.github.io/mm-docs-template/docs.pdf) of [single demo page](https://majkinetor.github.io/mm-docs-template/demo).
See entire docs as a [single page](https://majkinetor.github.io/mm-docs-template/print_page/) and/or [download](https://majkinetor.github.io/mm-docs-template/download/) it.
## Features
- Documentation in Markdown, HTML, PlantUML, MatJax
- Beautiful responsive design using the [material](https://squidfunk.github.io/mkdocs-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
## Prerequisites
- Docker installation.
- For Windows Desktop use: `cinst docker-desktop`
- PowerShell (optional)
- [Invoke-Build](https://www.powershellgallery.com/packages/InvokeBuild) module
## Usage
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:
```sh
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.
## Adding documents
- 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`
## Notes
- To build only specific section (using `ib -aSection `), make sure you have `regex: []` under `exclude` plugin. Because mkdocs builds all pages no matter if they are present in the `nav` section or not, this plugin option is used to NOT build other sections.