Skip to content

mkdocs

MkDocs is a static site generator for building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

I chose mkdocs to build the site because of its simplicity.

Link to site.

Some other options: hugo.

My install

Install a virtual environment such as virtualenvwrapper.

Create your virtual environment and activate it:

mkvirtualenv hackinglife

workon hackinglife

Install mkdocs. It's version 1.5.3. in my case:

pip install mkdocs==1.5.3

Install material theme for mkdocs: 

pip install mkdocs-material

Install plugins such as glightbox:

pip install mkdocs-glightbox

Install plugins such as "git-revision-date-localized"

pip3 install mkdocs-git-revision-date-localized-plugin

Install plugins such as "mkdocs-pdf-export"

pip install mkdocs-pdf-export-plugin

Customizing Material theme: pluggins and extensions

Some plugins like "mkdocs-glightbox", "mkdocs-git-revision-date-localized-plugin", or "mkdocs-pdf-export-plugin", need to be added when the web app is deployed, so for that reason they are added at .github/workflow/doc.yml.

But some other pluggings just need to be added in the mkdocs configuration file (mkdocs.yml) like this:

markdown_extensions:
    - extensionName

Admonition extension

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

In mkdocs.yml: 

markdown_extensions:
    - admonition
    - pymdownx.details 
    - pymdownx.superfences

Basic syntax

Code in the document:

!!! note "title"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod 
    nulla.

How it is seen:

title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.

Admonitions follow a simple syntax: a block starts with !!!, followed by a single keyword used as a type qualifier. The content of the block follows on the next line, indented by four spaces

!!! <typeofchart> "title"

When Details is enabled and an admonition block is started with ??? instead of !!!, the admonition is rendered as a collapsible block with a small toggle on the right side.

These are the type qualifier: note abstract info tip success question warning failure danger bug example quote

Content tabs

Source: https://squidfunk.github.io/mkdocs-material/reference/content-tabs/

In mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

Code in the document:

=== "Left"
    Content

=== "Center"
    Content

=== "Right"
    Content

How it is seen:

Content

Content

Content

Data tables

Source: https://squidfunk.github.io/mkdocs-material/reference/data-tables/#customization

In mkdocs.yml:

 extra_javascript:
      - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
      - javascripts/tablesort.js

After applying the customization, data tables can be sorted by clicking on a column-. This is code in the document

Data table, columns sortable
| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | Fetch resource  |
| `PUT`       | Update resource |
| `DELETE`    | Delete resource |

This is how it is seen:

Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource

PDF button in every page

Most of the existing plugins offer a print-all-in-one-file solution, which is not my intended development.

mkdocs-pdf-export-plugin

https://github.com/zhaoterryy/mkdocs-pdf-export-plugin

Install and add to gh-deploy workflow:

pip install mkdocs-pdf-export-plugin

mkdocs.yml

plugins:
    - search
    - pdf-export:
        verbose: true
        combined: false
        media_type: print
        enabled_if_env: ENABLE_PDF_EXPORT

/docs/css/extra.css

@page {
    size: a4 portrait;
    margin: 25mm 10mm 25mm 10mm;
    counter-increment: page;
    font-family: "Roboto","Helvetica Neue",Helvetica,Arial,sans-serif;
    white-space: pre;
    color: grey;
    @top-left {
        content: '© 2018 My Company';
    }
    @top-center {
        content: string(chapter);
    }
    @top-right {
        content: 'Page ' counter(page);
    }
}

https://octoprint.github.io/mkdocs-site-urls/

Revision date

https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/ ]

Install and add to gh-deploy workflow:

# Installs git revision date plugin globally
pip install mkdocs-git-revision-date-plugin

mkdocs.yml

# Adding the git revision date plugin
plugins:
- search
- git-revision-date
    type: timeago 
    timezone: Europe/Amsterdam 
    fallback_to_build_date: false 
    enable_creation_date: true 
    exclude: 
    - index.md 
    enabled: true 
    strict: true

This plugin needs access to the last commit that touched a specific file to be able to retrieve the date. By default many build environments only retrieve the last commit, which means you might need to:

  • github actions: set fetch-depth to 0 (docs)

Types

November 28, 2019           # type: date (default)
November 28, 2019 13:57:28  # type: datetime
2019-11-28                  # type: iso_date
2019-11-28 13:57:26         # type: iso_datetime
20 hours ago                # type: timeago
28. November 2019           # type: custom

To add a revision date to the default mkdocs theme, add a overrides/partials folder to your docs folder and update your mkdocs.yml file. Then you can extend the base mkdocs theme by adding a new file docs/overrides/content.html:

```yaml
theme:
    name: mkdocs
    custom_dir: docs/overrides
```

```html
<!-- Overwrites content.html base mkdocs theme, taken from 
https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/mkdocs/content.html -->

{% if page.meta.source %}
    <div class="source-links">
    {% for filename in page.meta.source %}
        <span class="label label-primary">{{ filename }}</span>
    {% endfor %}
    </div>
{% endif %}

{{ page.content }}

<!-- This section adds support for localized revision dates -->
{% if page.meta.git_revision_date_localized %}
    <small>Last update: {{ page.meta.git_revision_date_localized }}</small>
{% endif %}
{% if page.meta.git_created_date_localized %}
    <small>Created: {{ page.meta.git_created_date_localized_raw_datetime }}</small>
{% endif %}
```
Last update: 2024-03-29
Created: February 2, 2023 19:36:50