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.

1. Follow this Markdown styleguide.
2. Do not commit large files (e.g. very high-res images, binary data, executables)
   • Image optimization
3. Do not commit directly to master branch

Instructions to setup your local environment to allow for a live-reloading local server for development.

1. Clone this repo
2. Create a new conda env/ virtualenv
3. cd nersc-docs
4. 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

1. Create a new branch git checkout master && git branch my-new-page
2. Create/edit your content
3. Edit the mkdocs.yml file to include your content in the site
4. Check that your new content is built properly and without errors

   mkdocs build --clean --strict

5. Commit your changes
6. Submit a pull request for review