Skip to content

Contributing

Installation guide

This website is hosted by Github pages and built by mkdocs. Under the hood it uses github action to build the static page to gh-pages branch whenever a new commit is found on the the master branch. This is done by .github/workflows/ci.yml. In anycase if a deploy failed, please check the logs of github action.

To contribute to the website, you need to install mkdocs and mkdocs-material by following the instructions below:

Create and activate your virtual environment by:

1
2
 conda create -n mkdocs python=3.11
 conda activate mkdocs

Then install the following packages: 

1
2
pip install mkdocs-material
pip install mkdocs-macros-plugin

Now you are ready to clone the repository: 

1
git clone git@github.com:ImperialCollegeLondon/MSE404-MM.git
Note that you need to 🔗add your ssh-key to github before performing the clone.

Finally, go to the repo dir and spawn the server using: 

1
mkdocs serve
then you should be able to see the compiled website at http://127.0.0.1:8000. Any change you make to the markdown files will be automatically updated in the website so there's no need to re-do mkdocs server.

Now it's time to edit the files. The syntax is shown in the next section.

When you are done editing the files. Save the changes and deploy the website by: 

1
2
3
4
# stage the change
git add .
# commit the change with message.
git commit -m "message."

Before pushing the changes, make sure that you have the latest version of the master branch by:

1
git pull

Finally, push the changes to the remote repository by:

1
2
# push the change to the remote repository.
git push -u origin master
Note that you need to 🔗add your ssh-key to github before performing the push.

Writing guide

The following information is a shorter version of the official documentation of 🔗mkdocs-material. You can also find a similar one on our 🔗Group wiki.

  • Standard Markdown Syntax:
1
2
3
4
5
6
7
8
# Title
## Subtitle
### Sub-subtitle
#### Sub-sub-subtitle

_italics_

**Bold**

  • Adding a Hyperlink: 

    1
    [something](assets/test.in)

  • In-line code: 

    1
    this is a `line`.

  • Code blocks: 

    1
2
3
     ```python
 import numpy as np
 ```

  • In-line math: 

    1
    this is inline $\phi$ math

  • Math blocks: 

    1
2
3
    $$
\psi = \sum_a \phi_a
$$

  • Numbered list: 

    1
2
    1. test
2. test

    1. test
    2. test

  • Dot list: 

    1
2
    - something
- something

    • something
    • something

  • Table: 

    1
2
3
4
5
    | Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

    Method Description
    GET Fetch resource
    PUT Update resource
    DELETE Delete resource

  • Admonition (the indentation level N of admonition is determined by N*four spaces): 

    1
2
3
4
5
    !!! note "show up"
    something.

??? note "hide, click to show up"
    something

    show up

    something.

    hide, click to show up

    something

  • Code annotation: 

    1
2
3
4
5
     ```python
 some code #(1)!
 ```

1.  annotation

    1
    some code #(1)!

    1. annotation

  • Code highlight (highlight frist and second line): 

    1
2
3
4
5
6
     ```python hl_lines="1-2"
 some code
 some code highlighted
 some other code highlighted
 some code
 ```

    1
2
3
4
    some code
some code highlighted
some other code highlighted
some code

  • Emojis (https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/?h=emoji) 

    1
    :link:
    🔗

  • Images:

  • Center aligned (different syntax due to technical issues): 

    1
2
3
    <figure markdown="span">
  ![Diamond primitive cell](assets/Iron_bands.png)
</figure>
    Diamond primitive cell

  • Right aligned: 

    1
    ![MO](https://dummyimage.com/600x400/){ align=right}

    Some text. MO


  • Resize: 

    1
    ![Image title](https://dummyimage.com/600x400/){ width="300" }

    Image title

  • PNG files are prefered when showing structures of a material. You can export PNG with transparent background using VESTA.