Skip to content

Wiki update

These are basic instructions for updating this Wiki website, which is a streamlined version of the more general MkDocs User Guide.

Wiki Repository

This website is built from source code in the master branch of this GitLab repository.

To change the content of this Wiki website you need to follow these few steps:

  1. create a new branch, e.g. upd-howto from the master branch
  2. implement your changes in the new branch
  3. open a Merge Request into the master branch

Once the merge is done your updated version will appear online.

NOTE: You must have a CERN GitLab account and be a member of the Muon Collider GitLab group to have access to this repository.

To locate the folder or file responsible for a specific section of the Wiki that you want to modify it's helpful to look at the navigation list under the nav: tag in the mkdocs.yml file.

All these steps can be done directly through the GitLab website, which might be sufficient for simple editing of the existing ".md" files using the built-in Markdown editor. Yet for more substantial changes such as adding new pages or sections it is recommended to edit and host your version of the Wiki locally on your computer, before opening a Merge Request*.

Testing Locally

First ensure to have the appropriate Python environment with mkdocs package installed.

Virtual Environment

To not interfere with the system Python installation we'll create a virtual Python environment in the wikienv folder:

# Set up a virtual environment from your default python3 version
virtualenv -p $(which python3) ./wikienv
# Activate this environment
source wikienv/bin/activate

NOTE: This step is optional and may be skipped if you don't use the system Python installation in other projects sensitive to package versions.

Repository Update

Download the Wiki code repository and create a new branch with a unique name, e.g. upd-howto:

git clone https://gitlab.cern.ch/muon-collider/wiki.git
cd wiki/
git branch upd-howto
git checkout upd-howto

Local Server

Now install the mkdocs package and the material theme used by it.

pip install mkdocs mkdocs-material

Host the Wiki website by starting the local development server inside the wiki/ folder:

mkdocs serve

Point your web-browser to localhost:8000 to see the website.
The page will be automatically reloaded when you change any code inside the wiki/ folder.

NOTE: In case the default port 8000 is already used by another application, like Jupyter Notebook, you can provide a different port for the Wiki server, e.g. 8001: 

mkdocs serve -a localhost:8001

Push the Changes

After ensuring that your changes look good in the local server, push your branch to the repository:

git push origin upd-howto

Now create a New Merge Request on the GitLab repository page using master as a target and upd-howto as a source branch.