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]

I noticed that clicking “Create” hides the menu, but the “Status” menu works correctly. Is this the intended behavior?

[wwarriner]

I tested and can reprodudce. I have no explanation for why that happens, and we won't be getting any support to fix it as the mkdocs-material theme repository is in maintenance mode awaiting the release of Zensical.

This does NOT happen for the very next nav heading for Code.rc. My first guess is it's related to the fact that there are two lines on my browser. Or it could be a CSS-related issue, somehow.

For now we're going to have to live with it.

[bdu-birhanu]

I just tested other nav headings to see if they behave this way, and I found that the "Create" heading behaves like this because the account/rcs/create.md is referenced twice in the nav under mkdocs.yml.