Skip to content

Editing this site

Site organisation

The content of this site is made of markdown files compiled into a static website with Material for MkDocs. It is stored in a repository on IN2P3's Gitlab. Each time changes are pushed to the main branch, the website is built and published to the following address:

https://lbbe.pages.in2p3.fr/poleinfo/pole_info_documentation/

Edit directly on Gitlab

It is possible to edit the content of an existing page directly on Gitlab:

  • Go to the docs folder of the project repository
  • Browse and select the markdown file you want to modify
  • Click on the blue Edit button and choose Edit single file
  • Edit the content and commit your change

Edit locally

To edit this website locally you have to clone the website repository. You can then edit or add markdown files in the docs folder, commit and push your changes and they will be automatically published.

If you want to be able to preview your changes before pushing them, you must install uv (python project management tool), and then run the following at the project root:

uv run mkdocs serve

A website preview will be available at http://127.0.0.1:8000/poleinfo/pole_info_documentation/. This preview will be automatically updated as soon as you change the content of the markdown files.

Folders and files structure

The content of the website is in the docs folder. Any markdown file in this folder will create a page on the website. Apart from the assets folder, docs subfolders will create a section in the website sidebar.

The title of a page is taken from its first heading.

French translation

The website is in english by default, but it is possible to add french translations for some pages.

To do that, create a new markdown file with the name but by replacing the .md extension by .fr.md. So if you want to translate the page about/contact.md, create a file about/contact.fr.md.

You can then edit its content to add the french translation and it should be available when french is selected with the language toggle button in the top bar.

Markdown syntax

Markdown files follow the traditional markdown syntax.

To create links to other pages, use the classic markdown syntax to create a link to the markdown file. So if you are on about/editing.md and want to create a link to cluster/index.md, you can use:

[link to cluster](../cluster/index.md)

Tip

Some markdown extensions are available, such as admonitions which allows to easily create blocks like this one.

Admonitions / callouts

To create notes or warning callouts like the one above, use the following syntax:

!!! note

    This is a wonderful note.

You can replace note by warning, tip, info, danger, bug...

More details in material for mkdocs documentation.

Equations

To add mathematical annotations, you can use the LaTeX syntax surrounded by $ (for inline mathematics) or $$ (for block equations).

For example, the following code:

$$
\sum_{i=1}^n \sqrt{\frac{1}{x_i}}
$$

Will be rendered as:

\[ \sum_{i=1}^n \sqrt{\frac{1}{x_i}} \]

Images and attachments

Any static content such as images or PDF files must be put into the docs/assets/ folder.

To link to a static file you can use the normal link syntax:

[link to pdf](../assets/pdf/my_file.pdf)

To insert an image you can use:

![Alt text for the image](../assets/images/my_image.jpg)