Most pages

To change the navigation banner or footer of the pages, the configuration file mkdocs.yml should be edited.

In most cases, editing the content of a page simply means editing the Markdown file in the docs/ folder, however there are some exceptions:

• index.md
• resources/index.md
• resources/tags/*.md

These files all rely on data in .json format in the data/ folder, a Markdown template in the templates/ folder, and a Python script in the scripts/ folder to read the data and write corresponding HTML. An additional HTML template in the docs/assets/ folder is used to layout the banner for the About page (index.md).

This means to edit the content of these files, do not edit the Markdown file in the docs/ folder! These changes will be overwritten when the page is built.

Below we describe how to edit the content of these files.

Editing the About (home) page: docs/index.md

Summary

Section(s)	To edit content	To edit style
Navigation bar	mkdocs.yml	mkdocs.yml, docs/stylesheets/extra.css
Banner image	docs/assets/home.html, mkdocs.yml	docs/assets/home.html, docs/stylesheets/extra.css
Introductory text, section headers, "Where to Find Us"	templates/about_template.md	(no custom styles)
Profile cards	data/people/people.json, scripts/about_generator.py	docs/stylesheets/extra.css
Footer	mkdocs.yml	mkdocs.yml, docs/stylesheets/extra.css

1. To edit the main banner (background image and buttons):

The layout and style of this section is controlled by the raw HTML in docs/assets/home.html. It modifies the Material for Mkdocs base.html (Path in Material repo: src/templates/base.html) template. This file contains the special section {% block hero %}, which lets us add raw HTML content and styles between the navigation bar and the main content of the page. Some CSS is contained within this file because moving it to the extra stylesheet did not seem to work. Other styles are contained in docs/stylsheets/extra.css.

This section is set up as a simple grid with a background image and a transparent overlay that contains sub-grids for the buttons and space for a possible logo.

The button links and contents are currently set in the main configuration file, mkdocs.yml, but this may be unnecessarily complicated.

2. To edit the profile cards:

Profile cards are automatically added based on the entries in data/people/people.json. To add a person, simply add an entry in that file. People are ordered first by the department: ["Bioinformatics", "Software Operations"] and then by their title: ["Director", "Senior Bioinformatics Scientist", "Postdoctoral Researchers"] for Bioinformatics and ["Director", "Staff"] for Software Operations. Make sure each person has the status "active" or "moved".

To edit the HTML layout of the cards, edit scripts/about_generator.py. This script reads the profiles from data/people/people.json and inserts HTML into templates/about_template.md

To edit the style of the cards, edit docs/stylesheets/extra.css. See styles under /* Profile cards */ and /* Contact logo grid styles */.

3. To edit other content on this page:

To edit the introductory text for each section, the section headers, and the "Where to Find Us" section, edit the templates/about_template.md file. These changes will then be read in when scripts/about_generator.py runs and be reflected in the final site.

Editing the Resources page: docs/resources/index.md

Summary

Section(s)	To edit content	To edit style
Navigation bar	mkdocs.yml	mkdocs.yml, docs/stylesheets/extra.css
Section headers, "Workshops" and associated text	templates/resources_template.md	(no custom styles)
Tag buttons	data/resources/resources.json, scripts/resources_generator.py	docs/stylesheets/extra.css
Footer	mkdocs.yml	mkdocs.yml, docs/stylesheets/extra.css
Individual tag table pages (docs/resources/tags/*.md)	data/resources/resources.json, scripts/resources_generator.py, templates/tag_table_template.md	docs/stylesheets/extra.css

1. To edit the "External resources" tag buttons:

External resources are housed in the data/resources/resources.json file. This file is structured to contain both the "links" and the "tags" as top-levels of the data structure.

To add or edit an external resources, edit this file under the "links" level, using the template entry within the file.

IMPORTANT: If you add an external resources with a new tag, also add the tag under the "tags" level.

To edit the HTML layout of the tag buttons, edit scripts/resources_generator.py. This script reads the tags from data/resources/resources.json and inserts HTML into templates/resources_template.md.

To edit the style of the buttons, edit docs/stylesheets/extra.css. See styles under /* Tag link styles */.

2. To generate the tag tables (docs/resources/tags/*.md)

The scripts/resources_generator.py script also auto-generates one page for each tag by writing all links with the same tag to .csv files in data/resources/tag-csv/. These are then each read into their own page using the templates/tag_table_template.md Markdown template, which uses the {{read.csv()}} function from the mkdocs-table-reader-plugin (see requirements.txt) to automatically format the tables within Markdown. Most of the table formatting is done by this plugin, but to edit the HTML and styles of the tag link buttons, edit docs/stylesheets/extra.css. See styles under /* Table styles */ and /* Tag link styles */.

3. Editing other content on the Resources page:

To edit the content other than the "External resources" tag buttons, such as links, headers, and text, edit the Markdown template for the Resources page: templates/resources_template.md These changes will then be read in when scripts/resources_generator.py runs and be reflected in the final site.