Using MkDocs and GitHub to host our documentation.
Setting up an IDE is optional but we recommend the following tools.
- Visual Studio Code
- GitHub Desktop
- Git for Windows (Mac/Linux use system Git)
You need your own copy of the code to get started. This does require a GitHub account and you should sign up for a free account if you don't already have one.
To obtain a copy of the code, fork the main repo by clicking the Fork button on the main repo page https://github.com/mcw-rcc/mcw-rcc.github.io. This will create a copy of the main repository under your user account.
Finally, clone (i.e. download) the forked repository to your local machine using GitHub Desktop.
-
Clone the repo from
https://github.com/mcw-rcc/mcw-rcc.github.io
-
Create a new feature branch. Do not make changes to the main branch.
-
Setup a Python virtual environment
# MacOS/Linux terminal instructions python3 -m venv venv source venv/bin/activate python -m pip install -r requirements.txt
or
# Windows command prompt instructions python.exe -m venv venv venv\Scripts\activate.bat python.exe -m pip install -r requirements.txt
-
Start local server
# MacOS/Linux mkdocs serve
or
# Windows command prompt # Modify path to your venv python.exe -X utf8 D:\mcw-rcc.github.io\venv\Scripts\mkdocs.exe serve
-
Open a browser and enter
http://localhost:8000
To add a new page, edit the mkdocs.yml
file and add a new entry to the nav:
section.
For example, add a line to the software section:
- Software:
- Using Modules: software/modules.md
- Requesting Software: software/module-request.md
- Guides:
- software/R.md
- software/python.md
- software/tensorflow.md
- software/pytorch.md
- software/matlab.md
- software/schrodinger.md
- software/singularity.md
- software/my-new-guide.md
This will create a new entry in the site navigation for a page called my-new-guide.md
. If you're adding a page, make sure this page name is descriptive. For example, a page about GitHub might be called github.md
.
The page title that shows in the side navbar, and at the top of the page, will be the first entry in the page.
For our Github page:
# Learning GitHub
Remember to refresh your http://localhost:8000
browser session to preview your changes.
Work in progress.