Skip to content

How to create and manage an MkDocs website (like this one)

Page by G. Gamba and G. Sterbini

Introduction

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.

The website is hosted by the CERN web services and The openshift cloud platform is used to automatically update the website when changes are made int he GitLab repository.

Additional documentation

Detailed documentation can be found:

How to create the website

To setup an MKDocs website, the following steps can be followed:

  1. 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.
  2. Create a simple GitLab project. It can be empty at the moment.
  3. 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.
  4. 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

png

Then paste link in the Integrations settings of your GitLab project.

png

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.

Advanced features

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).

Install MkDocs

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
Then move on the abpcpweb folder
cd abpcpweb
and start the mkdocs server by
mkdocs serve

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

  1. activate mymdownx.arithmatex extension that is available by default in mkdocs container provided by CERN
  2. I sugesst also to activate admonition extension (and eventually other pymdownx extensions) for a nicer website.
  3. All this is done by adding the following lines in your mkdocs.yml configuration file:
    markdown_extensions:
        - pymdownx.arithmatex
        - admonition
    
    extra_javascript:
        - 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML'
    

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 docs/js/MathJax-2.7.5 3. replace the extra_javascript: configuration as following:

extra_javascript:
    - 'js/MathJax-2.7.5/MathJax.js?config=TeX-MML-AM_CHTML'

Using different branch

  1. Edit your "build" YAML configuration file on openshift: