Welcome

This a gathering of most of my documentation written while debugging and troubleshooting.

Mostly for 1 reason

I remember this problem ... but not the solution

So it will be a mix of chapters and a chronological troubleshooting list which is meant for 1 reader (myself) but by all means be my guest when a solution fits. Also I made cheatsheet collection that will find its way here as well, plus the google-docs, references and excerpts.
First a chapter about the tool that this site was made with :

Mkdocs

For full documentation visit mkdocs.org

tips

tips

I start with tips because I will need them building this documentation so the higher up the better.

links

open links in new tab

[link name](url){:target="_blank"}

simple link without title

<yoururl>

Internal links just take relative paths, example :

Please see the [project license](../about/license.md) for further details.

or in the [same directory](chapter2.md) 

line breaks

line break without a blank line

<br/>

admonitions

!!! warning "watch out !" 
    This will show a message in a warning box

watch out !

This will show a message in a warning box

Math

see visit for more info

This :

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$

Will render as :

\[ \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} \]

code

python code

``` py title="python code" linenums="1"

converting old documents from .rst

vim *.rst # and perform the next command for every file
:%s/::/.. code-block::/
rst_to_md.sh
vim *.md  # and perform the next command for every file
:%s/{.}/auto title="changetitle" linenums="1"/

Some explanation, pandoc only seems to convert code-block's to

``` {.}

So the last command searches and replaces that with a default code header.

The script below runs pandoc for every .rst file in the directory. After that it is manual labour :

• Auto does nothing, but it gives something to search for and change.
• So does changetitle.
• Also remove linenums if it does not make sense. Setting it to "0" works.

Actually, setting linenums higher makes it start at that line.

FILES=*.rst
for f in $FILES
do
  filename="${f%.*}"
  echo "Converting $f to $filename.md"
  `sed -i 's/::/.. code-block::/g' $f`
  `pandoc $f -f rst -t markdown -o $filename.md`
  `sed -i 's/{.}/auto title="changetitle" linenums="1"/g' $filename.md`
  `sed -i 's/\\\\\(.\)/\1/g' $filename.md`
done

After this script edit all *.md files and search for auto and changetitle and finish the conversion. Then remove the rst files.

The last line takes care of pandoc's escaping of characters like ',",\, into \',\",\\,\. It changes a backslash followed by one character into only that character. Otherwise we would have a problem with for instance postgres commands. pandoc make '\c' into '\\c' and just removing backslash make that a plain 'c' So this version works in almost all cases.

Deploy to nduss.nl

Deployment is done with ansible.

ansible-playbook playbook.yml

This should do the trick IF :

• you have provided a vault password in the file .vault_password.txt
• added vault_password_file = .vault_password.txt to ansible.cfg

Otherwise you should use the password option to ansible-playbook and ansible-vault.

Top menu

Just enable these all, it causes the highest level in your document hierarch to appear as tabs in your site. instant just makes it load faster. Visit the navigation page for all the possibilities.

using the top menu

features:
  - navigation.tabs
  - navigation.tabs.sticky
  - navigation.instant
  - navigation.tracking

Sticky means the menu stays visible if you scroll down.

Commands

• mkdocs new [dir-name] - Create a new project.
• mkdocs serve - Start the live-reloading docs server.
• mkdocs build - Build the documentation site.
• mkdocs -h - Print help message and exit.

Note that mkdocs server sometimes crashes with a message like

FileNotFoundError: [Errno 2] No such file or directory: '/home/kees/projects/doc/klopt/docs/data/databases/couchdb.md~'

This is because it detects a file that you were editing with vim, when you save and exit it detects changes in the vim swapfile couchdb.md~ but when it wants to process that file it is already deleted.

Disabling the swap file is probably best to avoid this. Create a local vimrc file and add .

set noswapfile

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.
site/
    index.html # etc, the generated site !
    ...

converting rst to md

Just a quicky, this one give almost good results ;)

rst2html hoek.rst | html2markdown > hoek.md

Just ignore error about spellings, delete them afterwards!

Material theme

The material theme has a lot of plugins and just looks neat. The documentation is also very good : visit

For instance this page that changes colors as direct example :

visit

pip install mkdocs-material

Note you can always visit mkdocs to see what the default theme looks like. Actually you can choose readthedocs theme out-of-the-box as well.

mkdocs.yml

A usable mkdocs.yml for the examples in the rest of this page is :

Note: i stopped updating this so it will be different now, just look in the source dir.

dev_addr: '127.0.0.1:8010'
site_name: My Docs
theme:
  name: material
  palette:
    scheme: default
    primary: orange

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite:
  - pymdownx.snippets:
  - pymdownx.tasklist:
      custom_checkbox: true
      clickable_checkbox: true
  - attr_list:
  - md_in_html:
  - pymdownx.superfences:
      custom_fences:
       - name: mermaid
         class: mermaid
         format: !!python/name:pymdownx.superfences.fence_code_format
  - admonition:
  - pymdownx.details:
  - pymdownx.tabbed:
      alternate_style: true 

custom css

One problem with the material theme is it does not use full screen width when you resize the width. Here is a small fix for that.

You can customize css by adding some extra css to mkdocs like this.

extra_css:
  - css/extra.css

And of course also provide the file :

docs/css/extra.css

@media only screen and (min-width: 76.25em) {
  .md-main__inner {
    max-width: none;
  }
  .md-sidebar--primary {
    left: 0;
  }
  .md-sidebar--secondary {
    right: 0;
    margin-left: 0;
    -webkit-transform: none;
    transform: none;   
  }
}

This indeed does the trick, both sidebars remain the same width and the middle column is widened. The menu is now centered but this is much better use of the given space.

source

external links

[mkdocs site](https://www.mkdocs.org)

Will render

mkdocs site

internal links

[hardware](hardware/ren.md)

hardware

It says .md here but the engine is smart enough to find the html equivalent.

admonitions

!!! note annotate "An annotation"

    with some text

An annotation

with some text

Or use other colors

!!! warning "Or use other colors"

Success

!!! success "Success"

code blocks

An example with title, linenumbers and highlight is

    ``` py title="bubble_sort.py" linenums="1" hl_lines="2-5 8"

# This is an example
class Math:
    @staticmethod
    def fib(n: int) -> Iterator[int]:
        """ Fibonacci series up to n """
        a, b = 0, 1
        while a < n:
            yield a
            a, b = b, a + b

result = sum(Math.fib(42))
print("The answer is {}".format(result))

diagrams

Using mermaid js, see here:

mermaid.js

Just to show it works :

    ``` mermaid
    graph LR
    A[Start] --> B{Error?};
    B -->|Yes| C[Hmm...];
    C --> D[Debug];
    D --> B;
    B ---->|No| E[Yay!];
    ```

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

code in separate tabs

=== "C"

    ``` c
    #include <stdio.h>

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

=== "C++"

    ``` c++
    #include <iostream>

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

Above code will show up like this :

CC++

#include <stdio.h>

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

#include <iostream>

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

box at the right side

!!! info inline end 

    some text that
    will pass the spelling checker 

Info

some text that will pass the spelling checker

With some more text , the box Will appear on the right side.

assets

One thing to note is where to put images etc. For instance let's take the logo image. The documentation says to put a line (almost) like this in mkdocs.yml

theme:
  logo: assets/images/klopt.png

Ok, but we have to provide the png file. And where to put that ? It should be in docs/assets/images/klopt.png as far as i see it.

Before running mkdocs build the site directory looks like this .

find site/assets/
site/assets/
site/assets/images
site/assets/images/favicon.png

So favicons was already there, and we did not put it there so it is default. Now these commands

mkdir -p docs/assets/images
cp klopt.png docs/assets/images
mkdirs build
find site/assets

This gives :

site/assets/
site/assets/images
site/assets/images/klopt.png
site/assets/images/favicon.png

Showing that the default and docs/assets/images are merge into one. Just as we want and both favicon an logo can be found.

titles and sort order.

To get the ordering you want, but also the title you want, prepend the file name with a number, and use a markdown Title. For instance name the directory or file "02-vue-tasks.md", but in the md file use set another title.

naming chapter titles and ordering

Title:   Vue Tasks App
Summary: Vue implementation of the tasks app.

Now the 02 will sort after 01, But the the title will be "Vue Tasks App". So the ordering follows the file names, but "Title" overrides the filename.

vue-lexer

To be able to use .vue files in mkdocs/pygments you can use

pip3 install vue-lexer

It can handle the combined html and js for vue files, but also it can be used to create svg files to further augment with annotations. An example, this code.

<div id="emit-example-argument">
  <advice-component v-on:advise="showAdvice"></advice-component>
</div>

const app = createApp({
  methods: {
    showAdvice(advice) {
      alert(advice)
    }
  }
})

app.component('advice-component', {
  emits: ['advise'],
  data() {
    return {
      adviceText: 'Some advice'
    }
  },
  template: `
    <div>
      <input type="text" v-model="adviceText">
      <button v-on:click="$emit('advise', adviceText)">
        Click me for sending advice
      </button>
    </div>
  `
})

app.mount('#emit-example-argument')

This can be made into an svg file with :

convert into svg file

pygmentize example.vue -f svg > example.svg

Then add some annotations in inkscape and add the image with

![Svg file](assets/images/example.svg){: style="height:650px;width:650px"}