08 Notable configuration settings in mkdocs.yml - harvardinformatics/informatics-website GitHub Wiki

Settings table

Setting	Description
site_name: Harvard FAS Informatics Group	Sets the name that appears in the upper left of all pages.
copyright: © 2023-2025 | Harvard FAS Informatics	Sets the copyright text to appear in the footer.
- navigation.tabs.sticky under theme: features:	Ensures that the navigation banner links stay at the top of the page while scrolling.
favicon: img/Icon_bw.png under theme:	Sets the image that appears next to the site name in a browser's tab.
logo: img/fas-shield-logo.png under theme:	Sets the image that appears next to the site name in the upper left of each page.
Under hooks:	All the custom scripts that will be run when the page is built.
Under extra: social:	The links and associated icons that will appear in the footer of each page.
home_cover_image: img/Icon_bw.png	The logo that will appear in the banner on the main page (currently DISABLED in docs/assets/home.html).
home_tagline: FAS Informatics	The main title text that will appear in the banner on the main page.
home_description: Bioinformatics training, collaboration, and research	The sub-title text that will appear in the banner on the main page.
home_button settings	Controls the text and links of the buttons in the banner on the main page.

Social cards

The built-in social plugin automatically generates images that are displayed when we share links to our pages (see also: basic social cards, setting up social cards). Without an "insiders" subscription, we get very limited control over how these look. But the settings we can control are in the mkdocs.yml file under plugins:

  - social:
      cards_layout_options:
        background_color: "#F3F4F4" 
        color: "#a51c30"
        font_family: Open Sans

For social cards, it is important that every page have a title and description set in the markdown front-matter, e.g.:

---
title: "Short page title"
description: "This description can be a bit longer and tell a bit about the contents of the page"
---

The title will be the main text on the social card and the description will be the smaller sub-text.

Disabling jupyter notebook rendering

When modifying the site locally, it can take a while to rebuild the site, which is annoying if you are making many changes. The time to rebuild can be drastically reduced by not re-rendering the jupyter notebooks for the workshops each time. To disable this, simply uncomment this line in mkdocs.yml:

# ignore: ['*.ipynb']

However, be sure to re-comment before pushing. To facilitate this, we have added a pre-commit hook (a script that runs as you commit your changes) that automatically looks at this line and re-comments it if it has been uncommented. In order to enable this pre-commit hook, you must configure github to look for scripts in this folder. While in the root folder of the project, run:

git config core.hooksPath .githooks

Then, during each commit, you should see the message Running pre-commit hook via sh....