How to create and manage an MkDocs website (like this one)
Page by G. Gamba and G. Sterbini
The website content is hosted in the form of markdown files on GitLab. The MkDocs generator automatically can be used to generate the formatted website from the markdown file.
Detailed documentation can be found:
- In the CERN IT documentation for MkDocs websites
- In the official MKdocs documentation
- In the documentation of the material theme (see in particular the Setup section)
How to create the website
To setup an MKDocs website, the following steps can be followed:
- Request the creation of a PaaS official website from the CERN web services. Choose a name, enter a description, and choose 'PaaS application' as site tipe. Once the request is made, it can take up to 20 minutes for the project to be created.
- Create a simple GitLab project. It can be empty at the moment.
- Create an MKDocs application through the configuration panel of the OpenShift service. You have to choose between the websites that you are hosting, and to enter the link of the corresponding GitLab project. When you enter the GitLab link, do not omit the ".git" at the end.
- In order to trigger an automatic regeneration of the website action when modifications are made in GitLab, you need to create a webhook. This is done in two steps. First, you need to go to the build configuration of your website on OpenShift, and get the "Generic Webhook URL" as shown in the picture
Then paste link in the Integrations settings of your GitLab project.
That should be it.
You can use this website as a template.
Tip (from Sondre): To access advanced customization features you might have to pin the theme version by including "requirements.txt" file. See for example the [COMBI documentation website](https://combi.web.cern.ch.
Access from outside CERN
By default, your website is accessible only from within CERN. To make it accessible from the internet, you need to change the site visibility from "intranet" to "internet". This can be done in the section Access and Permission on the site management page (https://webservices.web.cern.ch -> manage my website -> select [your site]).
How to edit the website
Te website can be edited: - Directly on GitLab, within the browser. - Locally, using git to clone the repository and push the modifications to GitLab. Visual Studio Code, which is free and available on Windows, Linux and Mac, is convenient to do the editing, providing features like a spell checker and a realtime preview of the markdown rendering.
Run the website as a local server
It is quite slow to edit your pages on gitlab website or even locally, then pushing them to git, and let the OpenShift server recompile the website for you. It is possible to have a local version of the site compiled directly. To do so you need to intall MkDocs within a recent python installation (python 3.5 or later).
Mkdocs can be installed with pip:
pip install mkdocs
Then please install some additional mkdocs theme:
pip install mkdocs-material
Compile your website
Clone a local version of your repository
git clone https://gitlab.cern.ch/abpcomputing/abpcpweb.git
You can now access the site on your browser at http://127.0.0.1:8000/ .
Changes in the markdown files will be automatically propagated to the local version of the site.
To update the version on the internet, you will need to commit and push your changes using git.
Adding support for latex
- activate mymdownx.arithmatex extension that is available by default in mkdocs container provided by CERN
- I sugesst also to activate admonition extension (and eventually other pymdownx extensions) for a nicer website.
- All this is done by adding the following lines in your mkdocs.yml configuration file:
If you want to add local MathJs, then you need to:
1. download to your repository the latest version of MathJax.
git clone https://github.com/mathjax/MathJax.git
2. add everything inside your docs folder, e.g. under
Using different branch
- Edit your "build" YAML configuration file on openshift: