Skip to content

Home

Jump to bottom
Gregg Thomas edited this page Jan 10, 2024 · 9 revisions

Welcome to the informatics-website wiki!

This site is made using the Material for MkDocs theme as a base for the theme and structure, plus custom HTML, CSS, and Python scripts. This wiki serves to document how the site works and how it is updated.

General description

  • data/ : This contains various .json files that contain site data for the Resources and About (home) page. When the page is built, several .csv files are also placed here to be turned into Markdown tables.
  • docs/ : This folder contains the Markdown pages used by MkDocs to generate the site. The structure of files and folders in this directory should directly mirror that of the navigation of the website set-up in the main mkdocs.yml config file. There are some extra folders (assets/ and stylesheets/) that are not directly related to the structure of the site that will be explained later.
  • scripts/ : Python scripts that read data from the .json files in data/ and generate HTML that is inserted into Markdown templates for the Resources and About pages. This occurs automatically when the site is built.
  • templates/ : Markdown templates for the Resources, Resource tag tables, and About pages.
  • mkdocs.yml : This is the main configuration file for MkDocs and includes parameters relating to website navigation, style, and even some content. See comments within the file.

Building locally to edit

To edit the site and its content, first clone the repository locally as you would any other repository. Then you will need to install the mkdocs-material package in a Python virtual environment so that the page can be built and served on a local web server.

  1. Initialize the virtual environment in the informatics-website directory:
cd informatics-website
python -m venv venv
  1. Start the virtual environment. This step alone differs based on operating system:

Unix/Mac:

source venv/bin/activate

Windows:

.\venv\Scripts\activate.bat
  1. Install mkdocs-material and start the local server:

Note that mkdocs-material requires Python 3.8+ and it may be a good idea to update pip before installing.

The mkdocs-table-reader-plugin also needs to be installed. This is used to build the tag table pages (see below).

pip install mkdocs-material
pip install mkdocs-table-reader-plugin
mkdocs serve

If that works, your terminal should hang, which is good -- it means that the web server is running. The last line should be something like:

INFO    -  [10:30:46] Serving on http://127.0.0.1:8000/

Just copy the URL you see into your browser and hit Enter and you should see the site! All changes made to any files in the docs/ folder, or any changes to the configuration file mkdocs.yml will automatically rebuild and refresh the site. Changes made to other files (e.g. .json files in data/, Markdown templates in templates/, generator scripts in scripts/) will require you to manually re-run the associated Python script in scripts/ in another terminal window in order for the page to be rebuilt and refreshed.

Editing 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.

Creating your own profile page

Each person associated with the group will have a profile card automatically generated for them on the About (home) page as long as their data is in data/people/people.json.

If you would also like your own personal profile page, feel free to create one in Markdown format in the docs/about/people/ folder (e.g. docs/about/people/timsackton.md). This can have any content you'd like, formatted easily with Markdown or even using custom HTML. You can even put other files in this folder and link to them from your page (e.g. a CV).

Once your page is created, add the path to the page as the "link" in your entry in data/people/people.json. Your profile card will now link to that page when the site is built!

Alternatively, if you maintain your own website outside of the Informatics website domain, simply add that URL as the "link" in your entry in data/people/people.json. Your profile card will then link out to your site.

Custom styles

For the custom HTML portions of the site, like the About page banner, profile cards, Resources page, tag tables, and Software page, we use corresponding custom CSS located in the docs/stylesheets/extra.css file.

A few important styles are described below.

1. The primary color scheme

The main black color (actually #262626) is set by first setting primary: custom under the palette: section in the configuration file mkdocs.yml. Then, in docs/stylesheets/extra.css, we set the main palette with:

:root {
  --md-primary-fg-color:        #262626;
  --md-primary-fg-color--light: #ec8f9c;
  --md-primary-fg-color--dark:  #6d1220;
}

Likewise, the light color for links throughout the site is set with:

.md-typeset a {
  color: #EF5552 !important;
}

And the link color in the footer is set with:

.md-footer-meta.md-typeset a {
  color: #ffffff !important;
}

Most other colors follow the default Material theme.

2. The CSS grid

For custom CSS layouts, a grid system is used to space out elements in rows throughout the site. This is specified under the /* Grid */ heading in docs/stylesheets/extra.css.

Briefly, the grid has a class, row, which fills 100% the width of its parent element. Within each row one can then place one or more col-N-24 elements, where N is any integer between 0 and 24. As long as the N's of each element within a row add up to 24, then the content should fit nicely within the width of the row's parent.

For example:


<div class="row">
    <div class="col-2-24"></div>
    <div class="col-8-24"></div>
    <div class="col-4-24"></div>
    <div class="col-8-24"></div>
    <div class="col-2-24"></div>
</div>

This grid is used as the basis for all custom HTML layouts throughout the site.

3. Page Navigation and Table of Contents columns

By default, the Material theme brackets page content with a Navigation column on the left and a Table of Contents column on the right.

Navigation shows the directory structure as links from the current page, while the Table of Contents shows links for each header in the page.

Throughout the site, we have disabled the Navigation column and shifted the Table of Contents to the left side of the content. This is done within the Markdown file of each page (or its template) as follows:

  1. To disable the Navigation column, add this as a header in the Markdown file:
---
hide:
    - navigation
---
  1. To move the Table of Contents to the left, add this CSS snippet just below the header in the Markdown file:
<style>
    .md-sidebar--secondary {
        order: 0;
    }
</style>

4. Banner background image on main page (docs/index.md)

Recall that the main page docs/index.md is generated via a Markdown template, HTML template, and Python script. To change the background image in the banner, one needs to edit the HTML template for the banner: docs/assets/home.html.

In that file, find the embedded CSS styles for the class .banner-row-container and edit that path to the background-image:

.banner-row-container {
    .
    .
    .
    background-image: url(img/banners/IMG_7404.jpg);
    .
    .
    .
}

5. Responsive styles for smaller screens (mobile)

The Material for mkdocs theme is already responsive and changes styles and content depending on the size of the viewport.

For our custom styles, you will notice that many classes have two entries in docs/stylesheets/extra.css, usually with one being under a @media tag. For example:

.software-logo-cont {
  display: flex;
  justify-content: center;
  align-items: center;
}

@media (max-width: 1025px) {
  .software-logo-cont {
    min-height: 10vh;
  }
}

This means that for viewports with a width greater than 1025px, which is most desktop and laptop screens today, the first set of styles are applied. However, once the viewport width is less than 1025px, a new set of styles are applied. These styles may overwrite styles for the larger screen, or simply apply new rules to the element.

In the case of the example above, elements of class .software-logo-cont will keep their display:, justify-content:, and align-items: rules when the viewport is below 1025px, however a new rule will be applied in addition to those rules that says the minimum height of the element should be 10% of the vertical height of the viewport (min-height: 10vh;).

Images and icons

All images on the site are located in docs/img/. Images include profile pictures, software logos, and background banners. But any type of image can be added to this directory and then linked to in a given Markdown page.

Icons

Icons refer to images or decorated text that appear in-line with other text and scale with it. We use some icons that are bundled with the Material theme and some custom icons.

Material bundled icons

Specifying icons in the footer

For some of the icons in the footer and on the Contact page, we use icon sets that are bundled with the Material theme. See their docs for more information.

For the footer icons, these are set in the mkdocs.yml configuration file under extra: social:. In this section you specify entries that will appear in the footer with both an icon and a link, e.g.:

- icon: fontawesome/brands/slack
  link: https://fas-bioinformaticspub.slack.com/

for the Bioinformatics public Slack.

Here, the path to the icon is relative to its location in the Material theme, which can sometimes be difficult to discern and is not well documented. Here is the file structure of the icons within the Material theme github: Material bundled icon paths. The path itself in the Material repo is material/templates/.icons/. Use the links provided in the documentation to browse icons, and then find their associated file name at that path.

Also note that the icon files all have the .svg extension, but this is not included in the path to the icon.

Specifying icons in Markdown files

You can also use these bundled icons directly in Markdown files, as we do on the Contact page. In this case we use a different syntax:

:fontawesome-brands-slack:

In this case, the icon path is bracketed by colons (:), and slashes (/) are replaced with dashes (-).

These icons can also have custom styles applied using the following syntax:

:fontawesome-brands-slack: { .contact-icon }

Here, { .contact-icon } refers to a class in our custom CSS file docs/stylesheets/extra.css. We use this on the Contact page to keep the icon as a clickable link without changing its color to red.

For more information on using icons in Markdown files see this section of the Material docs.

Custom icons

We also use a couple of custom icons for the FAS RC logo and the Harvard shield logo. In order to use these as icons and not images, we first must tell the site where to look for them. We do this in the mkdocs.yml configuration file with the following:

  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - docs/assets/.icons

Note that docs/assets/ is the same folder where we put our template for the banner section on the About (home) page (docs/assets/home.html).

Now, any .svg images we place in that folder can be used as icons as described above. For example, in the footer:

    - icon: custom/fas-rc-logo
      link: https://www.rc.fas.harvard.edu/

or inline on a Markdown file, as in the Contact page:

:custom-fas-rc-logo:

See this section of the Material docs for more information on using custom icons.

"Icons" in the profile cards

Though the links to an individual's Google Scholar or github page in their profile card on the About page look like icons, they are actually images (see docs/img/icons/). This is because of all the extra custom styles applied to them.

Notable configuration settings in mkdocs.yml

  • site_name: Harvard FAS Informatics Group sets the name that appears in the upper left of all pages.
  • copyright: © 2023 | 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: are all the custom scripts that will be run when the page is built.
  • Under extra: social: are the links and associated icons that will appear in the footer of each page.
  • home_cover_image: img/Icon_bw.png is the logo that will appear in the banner on the main page (currently DISABLED in docs/assets/home.html).
  • home_tagline: FAS Informatics is the main title text that will appear in the banner on the main page.
  • home_description: Bioinformatics training, collaboration, and research is the sub-title text that will appear in the banner on the main page.
  • home_button settings control the text and links of the buttons in the banner on the main page.
Clone this wiki locally