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
This is an admonition box.
Important
This is an admonition box.
Warning
This is an admonition box.
Success
This is an admonition box.
This is an admonition box without a title.
Danger
This is an admonition box.
Failure
This is an admonition box.
Default
This is the default box
!!! 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 for1 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
CH3CH2OH
texta 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()
More Markdown content.
- list item a
- list item b
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
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩
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¶
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¶


Unordered Lists¶
- item
- item a
- other nested
- other nested
- item b
- item b
- item
- item a
- other nested
- other nested
- item b
- item b
- item a
Ordered Lists¶
1. item
1. item a
1. other nested
1. other nested
1. item b
1. item b
- item
- item a
- other nested
- other nested
- item b
- item b
- item a
Code inside a list¶
- `name`
- `list`
- `name`
- `name`
- `name`
namelistnamenamename
Code inside table¶
| Example | Bla | Foo | Bla | Bla |
| ------- | -------- | --- | -------- | -------- |
| `name` | `String` | Bar | `String` | `String` |
| `name` | Bar | Bar | Bar | Bar |
| Bar | `String` | Bar | `String` | `String` |
| 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
sitamet, consectetur
Titles¶
header 1
header 2
header 3
header 4