MkDocs¶

python -m pip install --upgrade pip
python -m pip install mkdocs
python -m pip install mkdocs-material
python -m pip install pymdown-extensions
python -m pip install markdown-blockdiag
python -m pip install markdown-include
python -m pip install mkdocs-with-pdf

curl -sL https://download.calibre-ebook.com/linux-installer.sh | sudo -E bash -

sudo apt-get install python-setuptools
python -m pip install wheel

$ python -m pip show cairocffi
Name: cairocffi
Version: 0.9.0
...

python -m pip uninstall  cairocffi
python -m pip install cairocffi==1.0.1

python -m pip install --upgrade pip
python -m pip install --upgrade mkdocs
python -m pip install --upgrade mkdocs-material
python -m pip install --upgrade pymdown-extensions
python -m pip install --upgrade markdown-blockdiag
python -m pip install --upgrade markdown-include
python -m pip install --UPGHRADE mkdocs-with-pdf

mkdocs serve # from within the project home

mkdocs build

site_name: Alinex Development Guide
site_description: A book to learn modern web technologies.
site_author: Alexander Schilling
copyright: Copyright &copy; 2016 - 2021 <a href="https://alinex.de">Alexander Schilling</a>

nav:
    - Home:
          - README.md
          - alinex.md
    - Languages:
          - Overview: lang/README.md
          - Markdown: lang/markdown.m
          - Handlebars: lang/handlebars.md

theme:
    name: material
    icon:
        logo: material/book-open-variant
    favicon: assets/favicon.ico
    language: en
    palette:
        scheme: slate
        primary: grey
        accent: dark orange
    font:
        text: Lato
        code: Roboto Mono
    features:
        - navigation.instant

repo_name: 'alinex/alinex.gitlab.io'
repo_url: 'https://gitlab.com/alinex/alinex.gitlab.io'
edit_uri: ''

extra:
    social:
        - icon: material/gitlab
          link: https://gitlab.com/alinex
        - icon: material/github
          link: https://github.com/alinex
        - icon: material/home
          link: https://alinex.de

extra_css:
    - assets/extra.css

@import url("https://fonts.googleapis.com/css2?family=Oswald&display=swap");

/* use image for color theme */
body,
.md-header,
.md-footer,
.md-tabs {
  /*    background-image: url('blue-tunnel.jpg');*/
  background-image: url("default.jpg");
  background-size: cover;
  background-attachment: fixed;
}
.md-container,
.md-search__inner {
  background-color: rgba(0, 0, 0, 0.9);
}
.md-footer-nav,
.md-footer-meta {
  background: transparent;
}

/* General style */
.md-typeset h1,
.md-tabs,
.md-header-nav__topic,
.md-sidebar {
  font-family: "Oswald", sans-serif;
}
.md-tabs a {
  font-size: 0.9rem;
}
.md-sidebar label {
  font-size: 0.85rem;
}
.md-sidebar a {
  font-size: 0.75rem;
  margin-top: 0.4em;
}
.md-typeset h1 {
  color: white;
}
.md-typeset__table th {
  border-bottom: 2px solid darkorange;
  font-weight: bold;
}
.md-typeset__table tr:nth-child(even) {
  background: rgb(61, 61, 76);
}
.md-typeset table:not([class]) tr:nth-child(even):hover {
  background-color: rgba(61, 61, 76, 0.035);
}

/* change link colors for grey theme */
.md-header-nav__button:hover {
  opacity: 1;
  color: darkorange;
  transition: color 0.5s;
}
[data-md-color-primary="grey"] .md-typeset a {
  color: #00ade2;
}
[data-md-color-primary="grey"] .md-typeset a:hover {
  color: darkorange;
}
.md-nav__item .md-nav__link--active {
  color: white;
}
.md-sidebar label,
.md-nav__item--nested > .md-nav__link,
.md-sidebar a {
  color: gray;
}
.md-nav__link:hover {
  color: darkorange;
}
.md-nav__link[data-md-state="blur"] {
  color: rgb(180, 180, 180);
}
.md-nav__item .md-nav__link--active {
  color: white;
}
.md-footer-nav__link {
  font-weight: bold;
}
.md-footer-nav__link:hover {
  opacity: 1;
  color: darkorange;
  transition: color 0.5s;
}
a.headerlink {
  color: gray;
}

/* display external links with icon */
div.md-content a[href^="http://"]:not([href*="alinex.gitlab.io"]):after,
div.md-content a[href^="https://"]:not([href*="alinex.gitlab.io"]):after,
div.md-content a[href^="//"]:not([href*="alinex.gitlab.io"])
{
  content: "↗";
  font-weight: normal;
  font-style: normal;
  font-size: 70%;
  vertical-align: top;
  display: inline-block;
  text-decoration: none;
}

/* attribute classes to be used via {: .class} */
.left {
  /* left align with text float on the right */
  float: left;
  padding-right: 20px;
}
.right {
  /* right align with text float on the left */
  float: right;
  padding-left: 20px;
}
.icon {
  /* change image size */
  width: 25%;
}
.border {
  /* add drop shadow */
  border: 1px solid #021a40;
  -webkit-box-shadow: 0px 0px 18px 5px rgba(0, 0, 0, 0.5);
  -moz-box-shadow: 0px 0px 18px 5px rgba(0, 0, 0, 0.5);
  box-shadow: 0px 0px 18px 5px rgba(0, 0, 0, 0.5);
}

/* special use tags ==...== */
mark,
.md-typeset mark {
  background-color: rgb(255, 253, 130);
  color: black;
  font-weight: bold;
}

/* blockdiag */
img[src*="%3Ctitle%3Eblockdiag%3C"] {
  background-color: lightgray;
}

plugins:
    - search

markdown_extensions:
    - extra
    - toc:
          permalink: true
    - pymdownx.caret
    - pymdownx.tilde
    - pymdownx.mark
    - admonition
    - pymdownx.details
    - pymdownx.superfences
    - pymdownx.tabbed
    - codehilite:
          guess_lang: false
          linenums: false
    - pymdownx.inlinehilite
    - pymdownx.betterem:
          smart_enable: all
    - pymdownx.emoji:
          emoji_generator: !!python/name:pymdownx.emoji.to_svg
    - pymdownx.keys
    - pymdownx.smartsymbols
    - pymdownx.tasklist:
          custom_checkbox: true
    - markdown_blockdiag:
          format: svg
    - markdown_include.include

plugins:
  - with-pdf:
      cover_subtitle: Framework running powerful deep tests for standalone use or to enhance monitoring
      cover_logo: https://assets.gitlab-static.net/uploads/-/system/project/avatar/12586261/images__1_.png
      output_path: alinex-checkup.pdf

ebook-convert site/$NAME.pdf site/$NAME.epub

extra_javascript:
  - assets/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

plugins:
  - pymdownx.arithmatex:
      generic: true

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

title: Test Page

# Test

...

# Heading 1

## Heading 2

### Heading 3

> This is a block quote in which only the first line of the paragraph needs
> to be indented by `>` but it can also be done on each line.

---

-   water
-   cola
-   beer

1. select
2. take
3. buy

-   [x] item 1
    -   [x] item A
    -   [ ] item B
            more text
        -   [x] item a
        -   [ ] item b
        -   [x] item c
    -   [x] item C
-   [ ] item 2
-   [ ] item 3

| Left | Center | Right |
| :--- | :----: | ----: |
| one  |  two   | three |
| 1    |   2    |     3 |

!!! note

    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.

!!! note "Individual"

??? note "Initially closed"

    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.

???+ note "Initially opened"

    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.

=== "Bash"

    ```bash
    #!/bin/bash

    echo "Hello world!"
    ```

=== "Explanation"

    This is only a short example of how to make tabs.

```sql
SELECT count(*) FROM my_table;
```

SELECT count(*) FROM my_table;

    #!/bin/bash
    grep $1 $2

    :::bash
    grep $1 $2

```python hl_lines="3 4"
""" Bubble sort """
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

""" Bubble sort """
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

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

blockdiag {
    // simple graph
    A -> B -> C -> D;
    A -> E -> F -> G;
}

blockdiag {
   A [label = "foo"];
   B [style = dotted];
   C [style = dashed];
   D [color = pink];
   E [color = "#888888", textcolor="#FFFFFF"];
   // Set labels to edges. (short text only)
   A -> B [label = "click", textcolor="red"];
   B -> C [style = dotted];
   C -> D [style = dashed];
   D -> E [color = "red"];
   // Set numbered-badge to nodes.
   F [numbered = 99];
   G [label = "", background = "http://blockdiag.com/en/_static/python-logo.gif"];
   H [thick];
   // Set arrow direction to edges.
   A -> F [dir = none];
   F -> G [dir = forward];
   B -> G [dir = back];
   G -> H [dir = both];
   C -> H [thick]
}

blockdiag {
  // branching edges to multiple children
  A -> B, C;
  D -> E <- F -- G <-> H;
}

blockdiag {
  A -> B -> C -> D -> E;
  // fold edge at C to D (D will be layouted at top level; left side)
  C -> D [folded];
}

blockdiag {
  // standard node shapes
  box [shape = box];
  square [shape = square];
  roundedbox [shape = roundedbox];
  dots [shape = dots];

  circle [shape = circle];
  ellipse [shape = ellipse];
  diamond [shape = diamond];
  minidiamond [shape = minidiamond];

  note [shape = note];
  mail [shape = mail];
  cloud [shape = cloud];
  actor [shape = actor];

  beginpoint [shape = beginpoint];
  endpoint [shape = endpoint];

  box -> square -> roundedbox -> dots;
  circle -> ellipse -> diamond -> minidiamond;
  note -> mail -> cloud -> actor;
  beginpoint -> endpoint;

  // node shapes for flowcharts
  condition [shape = flowchart.condition];
  database [shape = flowchart.database];
  terminator [shape = flowchart.terminator];
  input [shape = flowchart.input];

  loopin [shape = flowchart.loopin];
  loopout [shape = flowchart.loopout];

  condition -> database -> terminator -> input;
  loopin -> loopout;

  // Set stacked to nodes.
  stacked [stacked];
  diamond [shape = "diamond", stacked];
  database [shape = "flowchart.database", stacked];
  stacked -> diamond -> database;
}

blockdiag {
  // Define class (list of attributes)
  class emphasis [color = pink, style = dashed];
  class redline [color = red, style = dotted];

  A -> B -> C;

  // Set class to node
  A [class = "emphasis"];

  // Set class to edge
  A -> B [class = "redline"];
}

blockdiag {
  orientation = portrait

  A -> B -> C;
       B -> D;
}

The HTML specification
is maintained by the W3C.

_[HTML]: Hyper Text Markup Language
_[W3C]: World Wide Web Consortium

Footnotes[^1] have a label[^@#$%] and the footnote's content.

[^1]: This is a footnote content.
[^@#$%]: A footnote on the label: "@#\$%".

[^1]: The first paragraph of the definition.

    Paragraph two of the definition.

    > A blockquote with
    > multiple lines.

        a code block

    A final paragraph.

{ !.gitignore!}

This is a paragraph.
{: #an_id .a_class }

### A hash style header ### {: #hash }

[link](http://example.com){: class="foo bar" title="Some title!" }

image: silentstorm/pandoc-mkdocs

before_script:
  - pip install --upgrade pip
  - pip install mkdocs-material
  - pip install pymdown-extensions
  - pip install markdown-blockdiag
  - pip install markdown-include
  - pip install mkdocs-with-pdf

pages:
  stage: deploy
  script:
    - mkdocs build
    - rm -rf public
    - mv site public
  artifacts:
    paths:
      - public
  interruptible: true