KPN for MkDocs¶

Create a beautiful KPN project documentation¶

KPN Theme is a theme for MkDocs, an excellent static site generator geared towards project documentation. It is built using KPN Styles.

Quickstart¶

Install the latest version of KPN theme with pip:

pip install mkdocs-kpn

Append the following line to your project's mkdocs.yml:

theme:
  name: 'kpn'

What to expect¶

• Responsive design and fluid layout for all kinds of screens and devices, designed to serve your project documentation in a user-friendly way.
• Support for a lot of markdown extensions.

Change repo icon¶

# options: github | gitlab | bitbucket | gitea
extra:
  repo_icon: 'github'

Add version to site¶

Edit mkdocs.yml with

extra:
  version:
    provider: 'manual'
    version: 1.2.2

TODO: Add support for mike versioning

Getting started¶

About mkdocs¶

Mkdocs is a project that enables you into writing documentation for your project in a super fast and easy way.

First, you have to create a docs/ folder in the root of your project, inside it, you can start creating markdown (.md) files.

The main file of the documentation is called index.md. This can be configured by configuring the navigation setting in your mkdocs.yml file.

Once you finish writing your documentation, using the command line, mkdocs will get all of these markdown files and will output a rendered HTML website to the site/ folder.

That's it!

Installation¶

If you are starting from the ground up, you need to install mkdocs in your project.

python -m pip install mkdocs mkdocs-kpn

Usage¶

Creating a configuration¶

In the root of your project create a file called mkdocs.yml and put this initial configuration:

site_name: <My Website Name>

theme:
  name: kpn

markdown_extensions:
  - codehilite:
      guess_lang: false

For more settings check the Full Example at the bottom of the page.

Add search support¶

Just add to the mkdocs.yml the following:

plugins:
  - search:
      prebuild_index: true

A search input will appear. The search index is offline, so no backend is required.

Running commands¶

python -m mkdocs build

Will output the generated website into a site/ folder. Remember to add it to your .gitignore, the idea is for CI's to automatically build it.

python -m mkdocs serve

This command will run a webserver which will reload your browser as soon as you make a change. This is useful to see your documentation while you are writing it.

Full configuration example¶

Full mkdocs.yml example:

# Project information
site_name: 'KPN Theme'
site_description: 'A KPN theme for MkDocs'
site_author: 'Jon Doe'

# Repository
repo_name: 'kpn/mkdocs-kpn-theme'
repo_url: https://github.com/kpn/mkdocs-kpn-theme

# Copyright
copyright: 'Copyright © KPN'

# Google Analytics Disabled by default
google_analytics:
  - 'UA-XXXXXXXX-X'
  - 'auto'

extra:
  # Use the repo edit url instead of the link to the repo
  use_edit_url: false

# Extensions
markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true
  - footnotes
  - pymdownx.critic
  - pymdownx.emoji
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.tasklist
  - pymdownx.tilde

API Documentation¶

To document your API we recommend using mkdocstrings.

Extensions¶

Admonition - Block styled content¶

# location: mkdocs.yml
markdown_extensions:
  - admonition

!!! info "Info"
    This is an admonition box.

!!! important "Important"
    This is an admonition box.

!!! warning "Warning"
    This is an admonition box.

!!! success "Success"
    This is an admonition box.

!!! check ""
    This is an admonition box without a title.

!!! danger "Danger"
    This is an admonition box.

!!! danger "Failure"
    This is an admonition box.

!!! Example "Default"
    This is the default box

Language highlight¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences

def fun():
    print("holis")

kubectl apply -f manifest.yml

Line highlight¶

You can highlight using the output is like:

Footnotes¶

# location: mkdocs.yml
markdown_extensions:
  - footnotes

All the other pages are for¹ demonstration purposes with the navigation only.

All the other pages are for[^1] demonstration purposes
with the navigation only.

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Keyboard¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.keys

Use keyboard values: Ctrl+Alt+Del

++ctrl+alt+delete++

Critics¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.critic

To insert or remove text you can use {++insert me++} and {--remove me--} respectively. You can also denote a substitution with {~~substitute this~>with this~~}.

You can also highlight specific text with {==highlight me==}. Or even comment, which is generally done by highlighting text and following it with a comment: {==highlight me}{>>Add a comment<<}.

To insert or remove text you can use insert me and remove me respectively. You can also denote a substitution with substitute thiswith this.

You can also highlight specific text with highlight me. Or even comment, which is generally done by highlighting text and following it with a comment: highlight meAdd a comment.

Emojis¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.emoji

You can also use emojis:

:smile: :heart:

Mark¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.mark

Ability to add <mark></mark> by using ==hello== hello

Smart symbols¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.smartsymbols

KPN ™

I'd say ±8

KPN (tm)
I'd say +/-8

Tasklist¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.tasklist

Task List

• item 1
• item A
• item B more text
  • item a
  • item b
  • item c
• item C
• item 2
• item 3

Tilde¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.tilde

Delete me

CH₃CH₂OH

text_{a subscript}

~~Delete me~~

CH~3~CH~2~OH

text~a\ subscript~

More¶

Read more about the extensions in pymdown-extensions

Content tabs¶

# location: mkdocs.yml
markdown_extensions:
  - pymdownx.tabbed

=== "JS"

    ```js
    date = new Date()
    ```

=== "Python"

    ```python
    import datetime
    datetime.datetime.now()
    ```

=== "List"
    More Markdown **content**.

    - list item a
    - list item b

date = new Date()

import datetime
datetime.datetime.now()

PlantUML diagrams¶

This is a C4 model example

```plantuml format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="C4 Model"
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

!define DEVICONS https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons
!define FONTAWESOME https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/font-awesome-5
!include DEVICONS/react.puml
!include DEVICONS/python.puml
!include DEVICONS/postgresql.puml
!include FONTAWESOME/users.puml

LAYOUT_WITH_LEGEND()

Person(user, "Customer", "People that need products", $sprite="users")
Container(spa, "SPA", "react", "The main interface that the customer interacts with", $sprite="react")
Container(api, "API", "python", "Handles all business logic", $sprite="python")
ContainerDb(db, "Database", "Postgres SQL", "Holds product, order and invoice information", $sprite="postgresql")

Rel(user, spa, "Uses", "https")
Rel(spa, api, "Uses", "https")
Rel_R(api, db, "Reads/Writes")
@enduml
```

Add to mkdocs.yml

markdown_extensions:
- plantuml_markdown:
      server: http://www.plantuml.com/plantuml

Check plantum-markdown is installed by running: pip freeze | grep plantuml-markdown

If not present, run:

pip install -U plantuml-markdown

VS code extension for PlantUML

Mermaid diagrams¶

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

You may need to add the following to your configuration if it doesn't work right away

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
          - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_div_format

Printing to PDF¶

To print to PDF simple add the print-site plugin to your mkdocs.yml:

plugins:
  - print-site: # bottom of the plugin list
      add_print_site_banner: true
      print_page_title: "User Manual"

A new print icon will appear. If you click on it, you'll be redirected to a print-friendly version of all of your documentation. From there you can print to PDF using your browser's print functionality, normally Ctrl + P or in mac Cmd + P.

Browsers recommended: Google Chrome or Microsoft Edge, as they have better support for printing web pages to PDF.

For more options check mkdocs-print-site-plugin

If you need to send content to a new page, you can use the page-break class in your markdown:

# Title

foo bar

<div class="page-break"></div>

# New page

Markdown usage¶

Markdown is a simple language that will become HTML.

The syntax is quite simple, use this cheatsheet as reference.

Coming up next we'll see some examples

Code blocks and links¶

a link to kpn

a link to kpn also code

variable = 1

Code block¶

In order to add a code block you need to wrap your coude around 3 backticks

```python
@requires_authorization(roles=["ADMIN"])
def somefunc(param1='', param2=0):
    r'''A docstring'''
    if param1 > param2: # interesting
        print 'Gre\'ater'
    return (param2 - param1 + 1 + 0b10l) or None

class SomeClass:
    pass

>>> message = '''interpreter
... prompt'''
```

Other languages:

groovy

stage("hello") {

}

typescript

const a = "A";

asciidoc

= Title

nix

{
    name = "x";
}

Image¶

![alternative text](https://www.kpn.com/public/images/logos/logo-kpn-groot.png)

Unordered Lists¶

- item
    - item a
        - other nested
        - other nested
    - item b
    - item b

• item
  • item a
    • other nested
    • other nested
  • item b
  • item b

Ordered Lists¶

1. item
    1. item a
        1. other nested
        1. other nested
    1. item b
    1. item b

1. item
   1. item a
      1. other nested
      2. other nested
   2. item b
   3. item b

Code inside a list¶

- `name`
- `list`
- `name`
    - `name`
    - `name`

• name
• list
• name
  • name
  • name

Code inside table¶

| Example | Bla      | Foo | Bla      | Bla      |
| ------- | -------- | --- | -------- | -------- |
| `name`  | `String` | Bar | `String` | `String` |
| `name`  | Bar      | Bar | Bar      | Bar      |
| Bar     | `String` | Bar | `String` | `String` |

Quotes¶

> Lorem ipsum dolor sit amet, consectetur

Lorem ipsum dolor sit amet, consectetur

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut ut tortor sed lorem auctor vulputate id hendrerit quam. Integer maximus molestie elit, non elementum libero rutrum ac. Suspendisse a gravida massa, vitae ullamcorper urna. Quisque various finibus leo, et ornare est bibendum et. Donec feugiat vitae ipsum fringilla volutpat. Duis hendrerit iaculis pellentesque. Nullam sed egestas nisi. Proin aliquet faucibus mi lacinia maximus. Integer urna ligula, malesuada in purus et, cursus tincidunt tortor. Donec et nunc consectetur, gravida nulla eu, viverra lorem. Nullam suscipit nibh sed nisl fringilla, sit amet tristique ante vulputate. Sed ultrices purus vel erat lacinia pellentesque. Phasellus elit mi, auctor eget nisl vehicula, sollicitudin ultrices risus. Etiam venenatis tempus arcu at dignissim.

Quotes with code block¶

> Lorem ipsum dolor `sit` amet, consectetur

Lorem ipsum dolor sit amet, consectetur

Titles¶