This repository contains NERSC technical documentation written in Markdown which is converted to html/css/js with the mkdocs static site generator. This file mainly describes how to contribute.
- Follow this Markdown styleguide.
- Do not commit large files (e.g. very high-res images, binary data, executables)
- Do not commit directly to master branch
Instructions to setup your local environment to allow for a live-reloading local server for development.
- Clone this repo
- Create a new conda env/ virtualenv
cd nersc-docs
pip install -r requirements.txt
In the root directory of the repository run mkdocs serve
and navigate your browser to the displayed address. Edits to source files will automatically trigger rebuilds of the site as needed.
To build a self-contained directory containing the full html/css/js of the site:
mkdocs build
- Create a new branch
git checkout master && git branch my-new-page
- Create/edit your content
- Edit the
mkdocs.yml
file to include your content in the site - Check that your new content is built properly and without errors
mkdocs build --clean --strict
- Commit your changes
- Submit a pull request for review