How to serve a site like this one¶

This site is based on MkDocs.

This is a simple yet powerful way of having a site based on MarkDown files.

Let's see how to configure it to serve either locally and on dev.mydomain.com site.

Note

Big thank you to Benjamin who helped me putting this site in place.

configure docker-compose on your server¶

You need to install and configure docker and docker-compose on you node see the docker and docker-compose pages.

Configure your MkDocs repository¶

Create your base directory, for instance /usr/local/services/MkDocs/. Then in this directory, create a file mkdocs.yml with the options and settings that you want for your site. For instance, here is my file:

# Project information
site_name: "Fabien's Dev pages"
site_description: 'My own Development Site using MkDocs'
site_author: 'Fabien Boutantin'
site_url: 'https://dev.boutantin.net/'
copyright: 'Copyright &copy; 2018-2022 Fabien Boutantin'

theme:
  name: 'material'
  language: 'en'
  font:
    text: 'Roboto'
    code: 'Roboto Mono'
  features:
    - navigation.tabs
    - navigation.tabs.sticky
  palette:
    scheme: slate
    primary: 'deep orange'
    accent: 'deep orange'

nav:
    - Home: index.md
    - Linux:
      - Service Configuration:
        - MkDocs (this site) [en]: Linux/Infra/Services/MkDocs.md

# Customization
extra:
  search:
    language: 'en, fr'

# Extensions
markdown_extensions:
- admonition
- footnotes
- toc:
    permalink: true
- pymdownx.highlight
- pymdownx.superfences
- pymdownx.details
- pymdownx.tabbed
- pymdownx.tasklist:
    custom_checkbox: true

You can change the values according to your needs.

Note

the navigation bar can be tweaked with multiple levels and pages.

Then you need to create a directory docs in which you will put all your content. In my example, I have a file docs/Linux/Infra/Services/MkDocs.md (which you are currently reading ;) ). Navigation files are relative to this docs directory.

According to the mkdocs.yml file in this section, you shoudl also create a docs/index.md file that will be your entry point for your site (some kind of index.html).

Configure Docker-compose¶

Now that you have done the first setup of your site, you will have to configure the docker access to your site.

To do so, create a docker-compose.yml file right here in /usr/local/services/MkDocs/ with this content:

version: '3'

services:
  mkdocs:
    container_name: mkdocs
    image: squidfunk/mkdocs-material:latest
    restart: unless-stopped
    ports:
      - 9000:8000
    volumes:
      - ./:/mkdocs
    environment:
      - LIVE_RELOAD_SUPPORT=1
    working_dir: /mkdocs

This will run container based on image provided by squidfunk which will restart when server restarts (restart option).

This will serve the site on port 9000 (which you can change if you need).

Note

that the service is in automatic update of the site mode (LIVE_RELOAD_SUPPORT=1). This is helpful when you write your site: you can see the changes on your pages directly in the browser. To serve a "static" version of your site, this is less important and can save some resources.

Starting the service¶

To start the service, simply run this command in your installation directory (/usr/local/services/MkDocs/):

docker-compose up -d

You will then be able to see your site on this page http://localhost:9000

Configure your reverse proxy¶

In order to have things works correctly, you will have to configure all the stuff in Apache configuration file.

You can find some information about how to configure your reverse proxy here.

For instance, if your server's IP is 123.170.5.250 and you leaved the port on 9000

(...)
<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        ServerName dev.mydomain.com
        ServerAlias dev.mydomain.com
(...)
    ProxyPass / http://123.170.5.250:9000/
    ProxyPassReverse / http://123.170.5.250:9000/
    ProxyRequests Off
    AllowEncodedSlashes NoDecode
(...)
  </VirtualHost>
</IfModule>

This way you will be able to serve this service for internet access.

2 words on formatting:¶

You can find information there.

Here is a little summary of what can be used with this configuration.

Admonition:¶

!!! note "Optional title (can be empty string for no title at all)"
    tototiti

will render like this:

Optional title (can be empty string for no title at all)

tototiti

You can use note, warning, important, etc (see python-markdown documentation)

Details¶

You can use foldable abmonitions like this:

??? "title for details"
    titutitu

which will render like this:

title for details

titutitu

Tables¶

| Method      | Description     |
| ----------- | --------------- |
| `GET`       | Fetch resource  |
| `PUT`       | Update resource |
| `DELETE`    | Delete resource |

Method	Description
`GET`	Fetch resource
`PUT`	Update resource
`DELETE`	Delete resource

Tabbed code blocks¶

You can tab code blocks by using:

=== "Python 2.x"
    ```python
    print "Hello, world!"
    ```
=== "Python 3.x"
    ```python
    print("Hello, world!")
    ```

Python 2.xPython 3.x

print "Hello, world!"

print("Hello, world!")

Note

It is possible to add more stuff in the tab section to tab more than code blocks.

Footnotes¶

To add a Footnote simply write this:

My text is[^1]

My definition is:
[^1]:
    my text starts here
    and continue there.

    Add it is at the end of the page.

My text is¹

Task Lists¶

You can create task lists as simply as that:

- [x] Task 1
- [ ] Task 2
    - [x] Task 2-1
    - [ ] Task 2-2
    - [x] Task 2-3

Line numbers on codeblocks¶

Simply add linenums="FIRST_LINE_NUMBER" to your code block definition like this:

 ```python linenums="5"
 def my_function(*args, **kwargs):
     print(args)
     print(kwargs)
 ```

def my_function(*args, **kwargs):
    print(args)
    print(kwargs)

my text starts here and continue there.

Add it is at the end of the page. ↩