MM-DOCS↵

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 docker bundle:

• https://github.com/majkinetor/mm-docs

Features↵

• Write documentation in extended Markdown, HTML, PlantUML and other markup languages
• Beautiful responsive design using material theme
• Navigational bar, TOC, search, internationalization, and various rich presentation functionalities
• Rich diagrams and interface mockups using PlantUML
• Macros can be written in python
• PDF export for each page or full site
• Single page with entire documentation
• Live reload during editing
• GitLab/GitHub repository connection for editing within a browser
• Automated AppVeyor build and deploy to GitHub pages using Ubuntu image
• Cross platform for hosting and development

Prerequisites↵

• Docker
• PowerShell (optional, developer friendliness)
  • Invoke-Build module

Quick start↵

To edit documentation:

• Clone/use new project template
• Add new documents somewhere in the source\docs hierarchy.
• Add document path to TOC (file: source\mkdocs.yml; yaml key: nav) to make page visible in the navigation section, otherwise, the page is available via direct link.

Start development server - run in PowerShell Invoke-Build Run. The command is syntax sugar for running docker containers. To build static site run Invoke-Build Build.

Demonstration page↵

mm-docs demonstration page.

For more details about included tools see:

• Mkdocs
• Mkdocs Material Extensions
• PlantUML
• MathJax
• Jinja

Customization↵

• Color palettes
• Language
• Extending theme

Text↵

Unicode: Мислим дакле постојим

Basic effects↵

Subscript and supscript:

- H~2~0
- A^T^A

• H₂0
• A^TA

Buttons↵

[Subscribe to our newsletter](#){ .md-button }

Subscribe to our newsletter

Local files and images↵

![omg-lolcat](files/omg-lolcat.jpg)

To align image and add some text next to it you must put in div with class result:

<div class="result" markdown>
![omg-lolcat](files/omg-lolcat.jpg){ align=left }
</div>

Hotkeys↵

Links, footnotes and comments↵

Links↵

Magic links and emails: turned to links as recognized

Footnotes↵

A text with a short footnote[^short]
[^short]: https://en.wikipedia.org/wiki/Note_(typography)

A text with a short footnote¹

A text with a long footnote[^long]
[^long]:
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    massa, nec semper lorem quam in massa.

    ```
    code

A text with a long footnote²

Comments↵

The text contains 2 comments bellow this line which should not be visible.
[comment]: # (Developed using Visual Studio Code with plantuml extension: cinst visualstudiocode; code --install-extension jebbs.plantuml)
[comment]: # (PlantUML version may influence diagrams. This document is developped with 1.2017.15: cinst plantuml --version 1.2017.15)

The text contains 2 comments bellow this line which should not be visible.

Citations↵

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. Inline:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

code in citations

Another citation line

HTML↵

HTML is allowed without restrictions. Custom styles are added in docs\_css\extra.css file.

<div style='background-color: #fdd; padding:1em; text-align: center '>
    <font size="20">
        <span class="yellow bred pl1 pr1">cookies</span>
    </font>
</div>

Critic and comments↵

Here is some incorrect Markdown. I am adding this here. Here is some more text that I am removingtext. And here is even more text that I am adding.   Paragraph was deleted and replaced with some spaces.

Spaces were removed and a paragraph was added.

And here is a comment on some textThis works quite well. I just wanted to comment on it.. Substitutions isare great!

General block handling:

Emoji and icons↵

Use more than 7.000 icons and thousands of emojis in your project documentation with zero effort. Custom icons can be added and used in mkdocs.yml, documents and templates.

• More info
• List of emoji codes

Examples:

• :tada:
• :jack_o_lantern:
• :alien:
• :robot_face:
• :smile:
• :heart:
• :thumbsup:

• – :material-account-circle: (icon in .icons/material/account-circle.svg)
• – :fontawesome-regular-face-laugh: (icon in .icons/fontawesome/regular/face-laugh.svg)
• In a link

Lists↵

Ordered list↵

1. List item 1
2. List item 2
   1. List item 2.1
   2. List item 2.2
      1. List item 2.2.1
      2. List item 2.2.2
   3. List item 2.3
3. List item 4

Unordered, mixed↵

• List item 1
• List item 2
  • List item 2.1
  • List item 2.2
    1. List item 2.2.1
    2. List item 2.2.2
  • List item 2.3
• List item 4

Tables↵

Plantuml↵

Add plantuml in a block code header to set code section as PlantUml source. Use format to specify output type:

```plantuml format="svg"
title PlantUml Demo
left to right direction
skinparam packageStyle rectangle
actor customer
actor clerk
rectangle checkout {
  customer -- (checkout)
  (checkout) .> (payment) : include
  (help) .> (checkout) : extends
  (checkout) -- clerk
}
```

Mermaid↵

```mermaid
sequenceDiagram
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!
```

sequenceDiagram
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

MathJax↵

The block code:

```
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$
```

Inline math expressions: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$

Inline math expressions: \(p(x|y) = \frac{p(y|x)p(x)}{p(y)}\)

NOTE:

• This doesn't render corretly in PDF output, see this issue for explanation.

Admonition↵

More info

some code

Code Highlight↵

More info

import tensorflow as tf

With tabs:

#!/bin/bash

echo "Hello world!"

Write-Host "Hello world!"

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
}

#include <iostream>

int main() {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

using System;

class Program {
  static void Main(string[] args) {
    Console.WriteLine("Hello world!");
  }
}

Abbreviations↵

The following are defined in single file, _inc\abbr.md and included on each page.

• IT, XML, JSON

Smart symbols↵

• (tm) ™
• (c) ©
• c/o ℅
• +/- ±
• --> →
• <-- ←
• <--> ↔
• =/= ≠
• 1/4 ¼
• 1st 1^st

Task list↵

• Lorem ipsum dolor sit amet, consectetur adipiscing elit
• Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
• Vestibulum convallis sit amet nisi a tincidunt
  • In hac habitasse platea dictumst
  • Praesent sed risus massa
• Nulla vel eros venenatis, imperdiet enim id, faucibus nisi

Macros↵

More details.

Jinja templates↵

You can do all the work you want with Jinja2, including defining pure macros, conditionals and for loops:

{% macro input(name, value='', type='text', size=20) -%}
  <input type="{{ type }}" name="{{ name }}" value="{{ value}}" size="{{ size }}">
{%- endmacro %}

{% input('username') }}
{% input('password', type='password') }}

Includes↵

You may use the include directive from jinja2, directly in your markdown code e.g.:

## Paragraph
{%include 'snippet.md' %}
{%include 'html/content1.html' %}

The root directory for your included files is in docs_dir.

You can also include parts of the file.

Environment variables↵

Environment variables can be used inside of configuration file mkdocs.yaml. More...

site_name: !ENV CI_PROJECT_PATH

Variables↵

Context↵

[(0, 'Page', "Page(title='Home', url='index.html')"), (1, 'Page', "Page(title='Demonstration', url='demo.html')"), (2, 'Section', "title = 'Extra', children = [Page(title='Variables', url='vars.html'), Page(title='Revision', url='revision.html')], _Section__active = False"), (3, 'Page', "Page(title='Download', url='download.html')")]

Page↵

Config↵

Frontmatter var - foo: bar

Revisions↵

Build Date: 2024-06-25 11:37:59

View revision.json

Download↵

You can consume this documentation off-line via:

1. PDF that you can download
2. Standalone single HTML page that you can save
3. Entire site in ZIP archive that you can unpack and use locally starting from index.html