Grids, Tabs, and Macros

[wwarriner]

Pull Request

Intent

A demonstration of what grids and grid cards, content tabs, and macros are capable of. The goal of this set of changes is to simplify our documentation's presentation and reduce the cognitive load of readers, while important making content easier to discover.

Proposed Changes

• Overhaul main index.md
  • Rework announcements using macros
  • Announcement content now held in res/announcements.yml
  • Add grid cards for key content to main page
  • Add grid cards for support resources
• Overhaul help/support.md
  • Rework page using macros
  • Add grid cards for support resources to each relevant section
• Overhaul account_management section of the documentation
  • Rename directory tree to account for shorter URLs
  • Restructure directory tree to better match content relationships and structure
  • Use content tabs to show only content relevant to the researcher using the documentation
  • Use grid cards to point to other pages where appropriate
  • Use macros to create single definitions for content reuse
  • Streamline text
  • Remove or migrate redundant and irrelevant information
• CSS improvements and additions to support grids, tabs, and announcements
• Addition of mkdocs-macros plugin
• Update mkdocs-table-reader-plugin for compatibility with mkdocs-macros
• Change build_env.yml for compatibility fixes
• Add template macros to /docs/_macro/ (using jinja2)
• Add python macros to /macros/ (grid card engine using YAML data)
• Add _template directories with jinja2 templates supporting the documentation in the same directory
• Change res to _res for better visibility
• Change images to _img for better visibility
• Add {% raw %} blocks where necessary to avoid unexpected jinja2 template interpretation
• Update internal links where needed
• Grid cards held in res/grid_cards.yml

Changes to Section Headers

There are many, we will need to carefully review the changes.

Changes to Page URLs

There are many, we will need to carefully review the changes.

Related or Fixed Issues

Related to #858, #1094, #1095,

Accessibility Checklist

I have ensured all of the following for new or changed content:

• all images have appropriate alt text. Guidelines
• all images with text have sufficient contrast ratio. Checker
• all image text is transcribed or described in body text.
• all technical terms, jargon, and abbreviations are introduced before they are used.

Style Checklist

I have done all of the following:

• searched for other relevant pages and crosslinked from my content to them.
• searched for other relevant pages and crosslinked from them to my content.
• added redirects in mkdocs.yml for any moved headers or pages.
• defined new technical terms, jargon, and abbreviations in the glossary.
• searched for existing technical terms, jargon, and abbreviations in the glossary and added crosslinks to them.
• properly formatted and introduced key branding terms. List here.

[bdu-birhanu]

Is the text “indent(4)” a command? Or was this text just typed by mistake?

[wwarriner]

The | indent(4) ensures the text coming from the Jinja {{ }} block is indented by 4 spaces. All content under a markdown block environment (such as the === tabs) must be indent by 4 spaces relative to the block environment.

The | indicates we want to pipe the output of the previous command renderer.render_cards() through the indent() command.

The indent() command comes from the MultiLineInclude Jinja extension, installed in build_env.yml and referenced in mkdocs.yml. Jinja doesn't do a good job of allowing multi-line content to be indented consistently, and over the last 15+ years they have never improved it. So, someone wrote an extension that handles this situation.

Jinja is most often used in HTML, where indentation has no semantic meaning. We're using Jinja in markdown, where indentation has a definite semantic meaning, indicating what content is contained within a markdown block environment. So, we MUST have correct multiline indentation when importing.

These are the kinds of things that need to be in the contributor guide.

[bdu-birhanu]

OK, this issue was that "| indent(4)" was outside the Jinja expression and was therefore rendered as plain text when I run mkdocs serve. Placing it inside the expression:

   )| indent(4))
 }}

resolves the issue.

[bdu-birhanu]

Everything looks good to me. Let’s move the | indent(4) inside the Jinja expression, and then it is ok to merge.