Editing Wiki pages¶

This page presents an overview of the steps necessary to modify the wiki and add new pages. It also contains examples for useful commands and can be used as a template for new pages.

More detailed information can be found here:

• markdown guide
• mkdocs homepage
• mkdocs material help

Setup¶

To Make Changes Online¶

This is a method adapted to making small changes, most likely to a single page. Go to the current version of the site here, navigate to a page you wish to modify and click the page's modification link :fontawesome-solid-pen:{style="height:0.95em"}. You will be taken to the Github GUI to make your changes, which you can later commit.

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.

To Make Changes Locally¶

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

git clone https://github.com/pylhc/pylhc.github.io
pip install mkdocs mkdocs-material mkdocs-minify-plugin

Create a branch (from master) and make your changes. You can run a local server by running

python -m mkdocs serve

from the top-level directory, and see the site rendered locally in your browser at localhost:8000. The rendered website will automatically reload upon changes to any file located in the docs directory.

Commit your changes to this repository, and open a pull request to get them approved once they are ready.

Adding a page¶

In order to add a new page, a new .md 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.

Guidelines¶

Pages are written in Markdown (file extension .md). A general overview of the syntax as well as some best practices can be found here. Additionally, to allow for easier comparison between two versions of a file, it is recommended to keep it to one sentence per line. Ideally, the line length is kept below 100 characters. 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 this.

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

Environments¶

General text formatting¶

These are basic markdown commands, repeated here for convenience. A more exhaustive list is available here. To create:

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

• italic text, surround the text with _text_.

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

  Note that all links are relative to the current document! The #-labels are created by headers automatically and can be omitted, in case you want to link to the page itself.

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

  Note that at the bottom of the file, an ID named bestwiki should be created, together with the hyperlink to the webpage, 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 accessable only with a CERN login can be marked like {target=_blank .cern_login} or from the CERN network like {target=_blank .cern_internal}.

• a quote such as the one just above:

  > to markdown, or not to markdown
  

• small hints to a difficult word, which appear on mouse over, add at the bottom of the file:

  *[difficult word]: helpful explanation
  

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

• a block math environment, use:

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

• a footnote, use [^1] in the text and add at the bottom of the page [^1]: Lorem ipsum.

Code listing¶

To highlight code inline, surround the text to highlight with `.

For creating a code block, surround the code with ```. Please make sure that the code block is separated from the text by one blank line. Additionally, please specify the language.

```python
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

Text Boxes¶

??? abstract "Paper Box"
    Textbox for adding papers.

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

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

??? tip "Tip Box"
    Textbox for adding useful tips to novice users.

Note that appending a + to ??? will result in an expanded box by default.

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

Various other commands¶

Tables¶

Tables in markdown look like this.

It can be created using

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

Images¶

To paste an image, use the following code.

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

To include a centered image with a caption, use the following code.

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

Images should be saved in assets/images, in an appropriately named folder.