Editing This Wiki¶

This website is built with zensical, the successor of mkdocs-material, and its content is based on markdown files. This page presents an overview of the steps necessary to modify or add pages, and build the website. It also contains examples for useful commands and can be used as a template for new pages.

Making Changes Online¶

This method is adapted to making small changes, most likely to a single page. Go to the current version of the site, navigate to a page you wish to modify and click the page's modification link at the top right of the page's content. You will be taken to the GitHub UI to make your changes, which you can commit directly.

Even new pages can be added directly online on GitHub, by navigating to the desired location and clicking on the Add File button. See the section about adding pages for more info about what is required for new pages to be accessible from the menu. Please note: as a lot of fancy styling is added by zensical, but only the basic markdown formatting is seen in the GitHub preview.

Making Changes Locally¶

For bigger changes, local development is recommended. Get a local copy of this repository, set up a Python3 environment and install the dependencies:

git clone https://github.com/pylhc/pylhc.github.io  && cd pylhc.github.io
python -m pip install -r requirements.txt

Create a branch (from master) and make your changes. You can run a local server by running, from the top-level directory:

zensical serve

The site will be rendered locally in your browser at localhost:8000, and the build will automatically re-trigger upon changes to any file located in the docs directory. Commit your changes, push them to the repository, and open a pull request to get them approved once they are ready.

Adding a Page¶

In order to add a page, a new .md file should be created in the appropriate location in the folder structure. A link to the page then needs to be added in the nav section of the mkdocs.yml in the root directory, together with an ID. The current navigation gives a clear example of how this works.

Content Guidelines¶

Pages are written in Markdown, with file extension .md. A general overview of the syntax as well as some best practices can be found on this markdown guide. Additionally, to allow for easier comparison between two versions of a file, it is recommended to keep it to one sentence per line. Following this, it is also recommended to not put links in the text, instead creating an ID at the end of the document and linking to it. See the formatting section below.

Different blocks of either code or text should be separated by one blank line. To create blocks of code, use fenced code blocks, which are created using triple backticks: ```. These blocks of code should be separated from the previous and following text by one blank line. To allow for syntax highlighting, the language should be specified. Below a basic example.

```bash
something code that does something
```

Markdown Elements We Use¶

The following displays markdown commands and tricks we use extensively in this website. A more exhaustive list of markdown features is available on the markdown guide.

General Text Formatting¶

The following are used to format text in various ways:

• For bold text, surround the text with **text**.

• For italic text, surround the text with *text*.

• For an internal link, use [link](../../resources/wiki.md#general-text-formatting).

  Note that all links are relative to the current document. The #-labels, called "anchors", are automatically created by headers and can be omitted, for instance to link to the page itself.

• For an external link, use [link][bestwiki]{target=_blank}.

  Note that at the bottom of the file, an ID named bestwiki should be created at the bottom of the page, together with the hyperlink to the destination, like so:

  [bestwiki]: https://pylhc.github.io/
  

  The specifier {target=_blank} is added to ensure pages open in a new tab. In the specifier, additional information on the accessibility can be added. Links accessible only with a CERN login can be marked like {target=_blank .cern_login} or from the CERN network like {target=_blank .cern_internal}.

• For a quote such as the one just above:

  > to markdown, or not to markdown
  

• For tooltips appearing when hovering content such as an acronym, which appear on mouse over, add at the bottom of the file:

  *[acronym]: helpful explanation
  

• For an inline math environment, surround the equation with dollar signs: $a^2 + b^2 = c^2$.

• For a block math environment, use double dollar signs above and below the block's content:

  $$
  a^2 + b^2 = c^2
  $$
  

• For a footnote¹, use [^1] in the text and add at the bottom of the page [^1]: Lorem ipsum. The number can be replaced with a word (i.e. [^name]).

Code Listing¶

To highlight code inline, surround the text to highlight with `. To create a code block, surround the code with triple backticks: ```. Ensure that the code block is separated from text by one blank line, above and below.

for i in range(3):
    print(i)

Additionally, specifying the language right after the backticks (here with ```python) will add syntax highlighting.

for i in range(3):
    print(i)

Lists¶

- First
- Second
- Third

1. First
2. Second
3. Third

- [ ] First
- [x] Second
- [ ] Third

- [ ] <details class="nodeco"><summary>Task 1 Summary</summary>
    <p> Hints for task 1.
    </p></details>

- [ ] <details class="nodeco"><summary>Task 2 Summary</summary>
    <p> Hints for task 2.
    </p></details>

- [ ] <details class="nodeco"><summary>Task 3 Summary</summary>
    <p> Hints for task 3.
    </p></details>

=== "Entry 1"
    Text 1
=== "Entry 2"
    Text 2
=== "Entry 3"
    Text 3

Admonitions¶

Styled text boxes, called admonitions, are a convenient way to convey specific relevant or important information. To see all supported admonitions types, see directly the relevant section in zensical's documentation.

They are declared with either !!! or ??? (for expanded or collapsed), the admonition type (which defines its styling) and optionally a title in quotes. This is followed by indented text for the admonition's content. Should the content span multiple lines, it is common to leave a blank line before starting it.

Here are a few examples including the code to create them. The collapsed ones can be expanded by clicking on them.

??? abstract "Abstract"
    Admonition useful for referencing papers.

??? info "Info Box"
    Textbox for adding useful information.

??? question "Question Box"
    Textbox for answering commonly asked questions.

??? tip "Tip Box - Expand Me!"
    Appending a `+` to `???` will result in a box expanded by default, but still collapsible.

    !!! info "Amonitions can be nested!"
        Any content in an admonition is treated as markdown.

!!! note "Note Box"
    Textbox for adding small notes.

!!! warning "Warning Box"
    Textbox for warning users of common pitfalls.

!!! danger "Danger Box"
    Textbox for warning users of potential serious consequences if not executed properly.

!!! todo "Todo Box"
    Textbox for warning users that this webpage is still work in progress.

Creating Tables¶

Tables in markdown look like this.

It can be created with:

| Column 1 | Column 2 |
|----------|----------|
| Entry 11 | Entry 21 |
| Entry 12 | Entry 22 |

When creating a table, please ensure that column width is constant and that pipes (|) are aligned. If using an IDE, this can be easily done with an extensions such as the markdown table formatter.

Inserting Images¶

To insert an image, use the following:

![Image](../assets/images/tricks/placeholder.gif)

To include a centered image with a caption, deferring to html also works:

<figure>
  <img src="../../assets/images/something/image.png" width=90%>
  <figcaption>Figure: Something really amazing.</figcaption>
</figure>

The specified source for the image is a relative path to the markdown file. Images should be saved in assets/images, in an appropriately named folder.