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
• events-workshops/previous-events.md
• workshops/ (see Workshops as submodules for more info)

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.

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

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.

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 */.

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.

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

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 */.

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 */.

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.

The previous events page tracks all of our past workshops and events. The lists of events are stored as .csv files in data/previous-events/<year>.csv

⚠️ Warning: Opening and saving these files with Excel will mess with the date formatting! Not tragic, but I like the dates formatted the way they are.

To add an event, simply open the appropriate year file in your favorite text editor (preferably not excel, as mentioned above), and input your data. The Event type is indicated by an icon (see Images and Icons), and you should put the MkDocs shortcut string to the icon directly in the csv. After you update the data tables, you will have to manually trigger a site rebuild (by making an unnoticeable change in mkdocs.yml a file in docs/) to see the new event show up on the page.

Event type	Icon shortcut string
Workshop	:material-tools:
Short training	:material-monitor-account:
Special event	:material-star-plus-outline:
Programming & Pizza	:fontawesome-solid-pizza-slice:

There is also some custom CSS at the top of the page to disable some of the MkDocs table formatting and add some custom formatting. You can generally ignore this.