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
• Profile pages
• Tag pages
• events-workshops/previous-events.md
• Publications lists on research/index.md
• workshops/ (see Workshops as submodules for more info)
• Jupyter notebooks

These files all rely in some way on data in the data/ folder, a template in the templates/ folder, or a Python script in the scripts/ folder to read the data and write corresponding HTML.

We'll explain these files more below, but first some notes about standard parts of the regular pages.

Markdown pages should have front-matter describing them. This front-matter may also be used for other parts of the page build. The most basic info should be a page title, but a short description should also be provided for search engine optimization and social cards.

---
title: "Short page title"
description: "This page has some content related to various things"
---

Here, the value of the title will be used as:

1. The level 1 header for the page
2. Replacement of the group name in the navigation banner as the site scrolls
3. The title of the browser window or tab
4. The main text on the page's social card

If the page has a separated level 1 header (# This is a level 1 header), then that will be used instead as the level 1 header, but the value of the title: in the front-matter will still be used in the navigation banner and tab or window.

Authors may also be listed in the front-matter:

---
author: John Doe
---

or

---
authors:
    - John Doe
    - Jane Doe
---

This is useful if we want to add an author row to the page that displays the profile image and name (if there are fewer than 4 authors) of each author. To add the author row, make sure the authors are specified exactly as above in the markdown's front-matter, and then add this to the markdown page content:

{{ author_row(page) }}

This is a Jinja call to a macro located in scripts/macros.py that uses the mkdocs-macros plugin to run this code as the site is built and insert the resulting HTML into the page. This macro depends on the data in data/people/people.json to look-up a person's profile image and profile page URL.

The author row also adds text that shows when the page was last updated using the mkdocs-git-revision-date-localized plugin.

The author row can be added anywhere in the page, but the best place is usually the top of the page.

By default, the header of the author row is Author: or Authors:. This can be changed by using the author_header: setting in the page's front-matter:

---
authors:
    - John Doe
    - Jane Doe
author_header: Workshop developers
---

This will add the author row with the label Workshop developers:

Author row styles can be edited in docs/css/author-row.css

All together, a typical markdown front-matter section may look something like this:

---
title: Biotips workshop day 4
description: The Harvard FAS informatics group bioinformatics tips & tricks workshop (biotips). Day 4 includes more instruction on shell scripting and best practices for reproducibility.
authors:
    - Nathan Weeks
    - Tim Sackton
author_header: Workshop authors
---

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/css/banner.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"]. Make sure each person has the status "active" or "moved".

The cards are generated by scripts/about_generator.py during site build with the mkdocs-gen-files plugin. This script reads the profiles from data/people/people.json and inserts HTML into templates/about_template.md using the card templates listed below.

To edit the HTML layout of the cards, edit the templates templates/active-cards.html and templates-alumni-cards.html.

To edit the style of the cards and their layout on the page, edit docs/css/cards.css.

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.

The resources page is no longer generated through a template and a script. Edit this file directly to edit the content

The tag index table for External resources is generated through Jinja in the markdown and macros in scripts/macros.py. The get_resources() macro loads the link data and it is then processed on the markdown page with Jinja. This occurs on site build.

To edit the styles of the tag index table, edit docs/css/tags.css under the "Tag index table styles" comment.

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. Each tag will have a page created automatically containing a table with every link that contains that tag.

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.

The tag pages are then generated on site build with the scripts/tags_generator.py script. This uses the mkdocs-gen-files plugin. To edit the layout of this page, edit the in-line template in the script. To edit the styles on the tag pages, edit docs/css/tags.css under the "Individual tag page table styles" comment.

Profile pages are generated on site build with the mkdocs-gen-files plugin using the templates/profile_template.md template and the scripts/profile_generator.py script. The script reads data from data/people/people.json and inserts relevant information into the template. It also reads through every markdown file in docs/ to gather pages authored by each person (as denoted by the authors: front-matter entry) to generate links to each one.

By default, only the short blurb in a person's data/people/people.json entry under the profile: key is used as a bio on a profile page. However, any markdown formatted text can be used instead by placing a file named firstname-lastname.md in the data/people/bios/ folder (e.g. data/people/bios/gregg-thomas.md). If this file exists, the text and markdown formatting from it will be used instead of the blurb from the .json file.

If you have files you'd like to link to (e.g. a CV or paper), place them in docs/people/files/.

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.

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

To edit the project summaries, simply edit the markdown file.

The publication lists are rendered by a macro in scripts/macros.py (render_publications). In the markdown, place the following where you want the list to be rendered:

{{ render_publications("<project-name>") }}

Valid project names as of 07.11.2025 are:

project_list = ["annotation", "worm-genomes", "parasitic-plant", "moa", "scrna-methods", 
                "axolotls", "scrna-ecology", "tube-worms", "transcriptome-assembly",
                "rnaseq-assessment", "scrub-jay", "coalescent-processes", "snparcher",
                "phyloacc", "convergent-comparative", "rotifers", "peak-calling", 
                "proteomics"]

The publication data itself is stored in and Endnote library in data/publications/fasifx-pubs.enl. To add a publication, open the library. If this is your first time opening the library you must activate the BibTeX style:

1. Activate the BibTeX style for exporting: Tools > Output Styles > Open Style Manager, check the box next to "BibTeX Export", close Style Manager.
2. Change the library's style to BibTeX export: Tools > Output Styles > Click "BibTeX Export".

Add the reference:

1. Add a reference to the library via Endnote's built-in search or import.
2. 🚨Important: Edit the reference so that the Keywords entry contains the keyword project:<project-name>. Save the reference.

And export to a BibTeX file:

1. Select all references in the library (ctrl+a).
2. Export to BibTeX format: File > Export, ensure "Output Style" is "BibTeX Export", change name to fasifx-pubs.bib, click "Save".

The updated BibTeX file will now automatically be read by the macro the next time the site is built.

⚠️ If you add a reference for a new project, you must also add the project name to the list in scripts/macros.py

⚠️ We mark current (bold text) and former (grad cap icon) group members in author lists so it is necessary to cross-reference author names in references with those in data/people/people.json. However, author names may be inconsistent between references. To account for this, we have added a bibtex-names entry for every person in people.json. If the reference you add has a different format for anyone's name, simply add it to that person's bibtex-names list.

Because the mkdocs-jupyter plugin lacks some functionality when converting jupyter notebooks to HTML, we have switched to using the native jupyter nbconvert command to convert to markdown which is then rendered to HTML by mkdocs. This is done through a GitHub action in the python-intensive submodule. This action runs the jupyter_convert.py script, which does the actual conversions, whenever there is a push action and the notebook files or the script itself has changes committed. The action is located at docs/workshops/python-intensive/.github/workflows/nbconvert.yml and the script is located at docs/workshops/python-intensive/.github/scripts/jupyter_convert.py.

The specific functions that mkdocs-jupyter lacked that are important for us are:

1. No way to add front matter to the markdown prior to conversion to HTML. We use front matter to specify page titles, descriptions, and authors, which are useful for social cards, SEO, and attributions on profile pages.
2. No (easy) way to add alt-text to images that are the result of running code blocks (e.g. figures generated by the code). Alt-text is important for accessibility

The jupyter_convert.py script does the following to accommodate these needs:

1. For each file specified, first convert to regular markdown with jupyter nbconvert.
2. Then edit the markdown to include other information, such as front matter, image alt-texts, link formatting, and styles.

Currently, the only jupyter notebooks rendered on the site are in the docs/workshops/python-intensive/. There are 6 notebooks. jupyter_convert.py has hardcoded information about each file stored in a dictionary that can be edited. For example:

    "Python-Day4.ipynb": {
        "title": "[Workshop] Python intensive, day 4",
        "description": (
            "Introduction to file handling and the numpy library for numerical computing "
            "in Python, including arrays and basic operations."
        ),
        "authors": ["Lei Ma", "Adam Freedman"],
        "alts": [
            "A pie chart titled 'Programming Language Popularity': Python 26.9%, Ruby 26.2%, "
            "C++ 30.6%, and Java 16.2%."
        ]

If these notebooks change, this information may need to be updated as well. If more notebooks are added, their information will need to be added to the dictionary. If many more notebooks are added, this likely won't be a scalable solution.

Each converted jupyter notebook also gets a style block added, specifically to make the code and output blocks look a bit more like a jupyter notebook. These can be edited in jupyter_convert.py as well. To test new styles, one may want to directly edit one of the existing converted markdown files and then copy the new styles into the template in jupyter_convert.py. Be sure you copy your new styles before you re-convert the notebooks or else the new styles will be overwritten and lost!