Blitzortung.org / Lightningmaps.org project documentation

This documentions is based on MkDocs. We use the material theme.

Quick start (git and python3 required):

git clone https://gitlab.lightningmaps.org/common/docs.git
pip install mkdocs mkdocs-material pymdown-extensions mkdocs-ezglossary-plugin \
    mkdocs-awesome-pages-plugin mkdocs-mermaid2-plugin mkdocs-link-marker \
    mkdocs-encryptcontent-plugin mkdocs-autorefs mkdocs-statistics-plugin \
    mkdocs-glightbox mkdocs-open-in-new-tab mkdocs-print-site-plugin \
    mkdocs-autolinks-plugin mkdocs-git-revision-date-localized-plugin \
    mkdocs-redirects mkdocs-plugin-progress mkdocs-minify-plugin

To build the documentation:

mkdocs build

To set up a webserver which live updates of your changes just run:

mkdocs serve

How To

Include the files

Files like firmware, schematics, pdf, ... reside in the "bo_files" repository. They are not needed for building the documentation. Downloads/Hyperlinks need them in the files directory (i.e Documentation is in site_name/docs, then files are in site_name/files). For development, you may want to clone them as described below.

Note: With mkdocs serve, the whole files directory is copied to to a temporary directory on every file change. For faster site generation you may want to use mkdocs serve --dirty.

Clone the files repository into the docs directory:

git clone ssh://git@gitlab.lightningmaps.org:2103/common/bo_files.git docs/files

or

git clone https://gitlab.lightningmaps.org/common/bo_files.git docs/files

Files which are non public (i.e. due to copyright reasons) can be cloned like this:

git clone ssh://git@gitlab.lightningmaps.org:2103/common/bo_files_extra.git docs/files/extra

or

git clone https://gitlab.lightningmaps.org/common/bo_files_extra.git docs/files/extra

Writing

An overview about basic syntax can be found here:

https://www.mkdocs.org/user-guide/writing-your-docs/

A lot of additional information is described for the materials theme.

https://squidfunk.github.io/mkdocs-material/reference/

Special Markdown

i.e. for Math formulas, progress bars

https://facelessuser.github.io/pymdown-extensions/#extensions

Navigation

We use Awesome Pages Plugin for easier navigation config (see .pages files)

https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/blob/master/README.md

Graphs

We use Mermaid for graphs. It's already included in materials theme and should not enabled in the plugin config.

https://mkdocs-mermaid2.readthedocs.io/en/latest/

Protected content

For password protection of internal documents.

See https://github.com/unverbuggt/mkdocs-encryptcontent-plugin

Enabling Privacy

We enabled the privacy plugin and using the cookie consent feature. Without consent no youtube videos will embedded.

Some extra javascript files are needed or won't get downloaded by the privacy plugin.

wget -O docs/extra/js/jquery-3.7.1.min.js https://code.jquery.com/jquery-3.7.1.min.js
wget -O docs/extra/js/mermaid.min.js https://unpkg.com/mermaid@10.6.1/dist/mermaid.min.js

wget -O docs/extra/css/glightbox.css https://raw.githubusercontent.com/biati-digital/glightbox/master/src/postcss/glightbox.css
wget -O docs/extra/js/glightbox.js https://raw.githubusercontent.com/biati-digital/glightbox/master/src/js/glightbox.js