Maintain this documentation

Contact/responsible: Marton Ady

This documentation is written using MKDocs, a static content generator which converts Markdown (.md) documents into html pages. In its CERN integration, the entire site's files are hosted on a Gitlab repo, and when a change (commit) happens, the public site is rebuilt and updated with using Gitlab automation.

All content, except the "blog" part, is static.

The blog section shows posts in the docs/blog folder in the order of Git commits using the MKDocs Blogging Plugin.

Markdown syntax

• Markdown cheatsheet
• Wikipedia Markdown article

Gitlab repo

All files of this website are hosted in this repository, clone it to have a local copy.

CERN MKDocs (internal)

Helps to create your own MKDocs-based website hosted at CERN, with the above setup (Gitlab repo published by Openshift).

Material for MKDocs

The MKDocs theme used for this website, supported by the CERN Openshift deployment.

MKDocs project

Official website of the MKDocs project powering this documentation.

To have a real-time local render of this documentation

You can display the documentation in your browser locally, without having to push commits and wait until they get published. Useful for "real-time" editing.

1. Clone the repository to a local folder:

   git clone https://gitlab.cern.ch/molflow_synrad/docs

2. Install python3, if you haven't already

   • Windows:
     • Get Chocolatey package manager
     • In command line or PowerShell, run choco install python (Python3 is already the default version)
   • Mac:
     • Get HomeBrew package manager
     • In Terminal run brew install python
   • Linux:
     • Debian: run sudo apt install python3

3. Install Pip (Python package manager), if you haven't (through brew, apt or choco)

4. Install mkdocs (through brew, apt or choco)

5. Install the Material module:

6. Windows: pip install mkdocs-material

7. Mac: python3 -m pip install mkdocs-material

8. Install plugins in the requirements.txt file (direct link) with Pip, for example pip install mkdocs-git-revision-date-localized-plugin

9. For the blog engine, you have to install a plugin, usage and demo site at https://github.com/liang2kl/mkdocs-blogging-plugin.

   For this site, the install procedure was:

   • Run default install command as administrator: pip install mkdocs-blogging-plugin
   • Edit mkdocs.yml:
     • Add site url in the file's header: site_url: https://molflow.docs.cern.ch/
     • Refer to the plugin:

       plugins:
           - blogging:
               dirs: # The directories to be included
                   - blog
       

   • For CERN Gitlab Pages deployment, add the plugin mkdocs-blogging-plugin to requirements.txt as a new line
   • You can then create .md notes in the docs/blog subfolder, which will be sorted by Git commit date

10. Run mkdocs serve

11. Open your browser at the address indicated by mkdocs serve, by default http://127.0.0.1:8000/

---

Render tests

Latex expression:

\(\frac{1}{\sin(x)}\)

Admonitions

Info

an info bubble

with code inline

Emojis

• Material design:
• FontAwesome:
• Octicons:

Full searchable list: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/

---

Last update: October 10, 2024