Grids, Tabs, and Macros #1104

wwarriner · 2025-10-29T00:01:31Z

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 · 2025-11-18T15:18:52Z

docs/account/rcs/create.md

+=== "External Collaborator (XIAS)"
+
+    The form should be prefilled as shown below. Only use the `name` portion of your XIAS email address `name@domain.tld` in the BlazerID field. Use your full XIAS email address in the Email field.
+


If this field is already prefilled, we could add "See incorrect or missing information? Please [contact support]." This would keep it consistent with the wording we used in the UAB Campus & UAB Medicine section.

bdu-birhanu · 2025-11-18T15:25:38Z

docs/account/rcs/create.md

+        cards.account.responsibilities
+    )
+}}
+


Would it be possible to move this content into a new section? E.g, under a heading like “RCS Services for Account Holders”? Because this current page is a bit overloaded.

bdu-birhanu · 2025-11-18T15:28:25Z

docs/account/rcs/create.md

+        renderer.render_cards(
+            cards.platforms.cheaha.ood.overview,
+            cards.platforms.cheaha.slurm.overview,
+            cards.data.individual_storage,


Would it be possible to mention that XAIS will not get Globus service that has subscription by UAB?

bdu-birhanu · 2025-11-18T15:32:11Z

docs/account/rcs/create.md

+    }}
+
+=== "Research Faculty Supervisor | Core Director"
+


Would it be possible to note that they may also receive all of the services provided to other users(students, staff, or XAIS guests)?

bdu-birhanu · 2025-11-18T15:35:03Z

docs/account/rcs/create.md

+            cards.platforms.cloud_rc.web_server,
+            cards.account.code_rc_create,
+        )
+    }} | indent(4)


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

bdu-birhanu · 2025-11-18T15:39:36Z

docs/account/rcs/status.md

+The following table has more information on each status, with links for more details. To check your status see [How Do I Check My RCS Account Status?](#how-do-i-check-my-rcs-account-status)
+
+{{ read_csv("_res/status_summary.csv", keep_default_na=False) }}
+


Is it possible to cross-link the certification page directly in the grid and remove this table( It seems a bit redundant)? The grid already presents the necessary information in a clearer way.

bdu-birhanu · 2025-11-18T15:44:24Z

docs/account/rcs/status.md

+
+=== "Pre-Certification"
+
+    When an account is in Pre-Certification status, all RCS services are accessible and action will be required soon.


Is that to mean "..RCS services are inaccessible.... "?

bdu-birhanu · 2025-11-18T15:46:09Z

docs/account/rcs/status.md

+
+    When an account is in Pre-Certification status, all RCS services are accessible and action will be required soon.
+
+    ?? days after entering Pre-Certification status, accounts will enter Certification status and action will be required. To prevent Certification status, you may certify at any time.


What do the double question marks represent here? Is it a typo?

bdu-birhanu · 2025-11-18T15:49:04Z

docs/account/rcs/status.md

+
+    ?? days after entering Pre-Certification status, accounts will enter Certification status and action will be required. To prevent Certification status, you may certify at any time.
+
+    While in Pre-Certification status, the [Account Status page](#how-do-i-check-my-rcs-account-status) will show "Account in Pre-Certification", as shown below.


The “Account in Pre-Certification” doesn’t appear in the image. This might be confusing for users. Should we remove this text or keep it?

bdu-birhanu · 2025-11-18T16:07:56Z

mkdocs.yml

+      - account/index.md
+      - Research Computing System (RCS):
+          - account/rcs/index.md
+          - Create: account/rcs/create.md


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

bdu-birhanu · 2025-11-18T16:12:05Z

mkdocs.yml

+          - 1. Sponsor — Manage Sites: account/xias/1_sponsor_manage_sites.md
+          - 2. Sponsor — Manage Users: account/xias/2_sponsor_manage_users.md
+          - 3. Guests — Create XIAS Account: account/xias/3_guest_create_xias_account.md
+          - 4. Guests — Create RCS Account: account/rcs/create.md


“Create” appears in the menu under "External Collaborators" and "Research Computing System (RCS)". Would it be possible to cross- link it and keep under either of the menus?

wwarriner added 30 commits September 23, 2025 12:36

enable emoji

1fc9862

Merge branch 'main' into feat-grid-cards

82a0623

add grid cards framework

c0f90a6

add yaml schemas for vscode

f7ee1d4

pre-migrate faq-style content out of account-mgmt

2e77f12

content cleanup

a1c4e4e

resolve tab anchor bug

0b2d4e5

add some j2 templates

851ab90

prepare machinery for cards

2eb0800

update account page to use cards and tabs

6038215

add missing admonitions

a610306

refactor macros and templates

e2d75d7

update leaving uab

c6fbfe0

add jinja2-workarounds extension to simplify indented includes

63c7ccf

update responsibilities page

277a36c

fix incorrect url in cards

86d1029

enable jinja rendering of card content

2946699

fix css for grid card lists

60eafc8

update grid cards with templated values

b4a060c

next steps for rcs create

3210633

add a few more grid cards to rcs

af5096d

add code.rc next steps

090e1c2

refactor and improve link normalization

455d679

add single-grid css card formatting

9ca6743

refactor help macros to support

14f6d7c

refactor meta, render all by default

cff99a4

add support cards

af363a0

refactor jinja context

e6196a2

fix broken icon

dad7a34

reorganize

466334e

wwarriner added 5 commits October 27, 2025 20:03

rename context yml

51b0321

make indent implementation consistent

3db7289

main index.md updates

a58c76c

Merge branch 'main' into feat-grid-cards

af51bbf

Merge branch 'main' into feat-grid-cards

5349e37

wwarriner added the pr: review PR is ready for review label Oct 31, 2025

wwarriner added this to the Sprint 26-03 milestone Nov 4, 2025

bdu-birhanu reviewed Nov 18, 2025

View reviewed changes

wwarriner modified the milestones: Sprint 26-03, Sprint 26-05 Dec 2, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Grids, Tabs, and Macros #1104

Grids, Tabs, and Macros #1104

Uh oh!

wwarriner commented Oct 29, 2025 •

edited

Loading

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025 •

edited

Loading

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025 •

edited

Loading

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

bdu-birhanu Nov 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		=== "External Collaborator (XIAS)"

		The form should be prefilled as shown below. Only use the `name` portion of your XIAS email address `name@domain.tld` in the BlazerID field. Use your full XIAS email address in the Email field.

		The following table has more information on each status, with links for more details. To check your status see [How Do I Check My RCS Account Status?](#how-do-i-check-my-rcs-account-status)

		{{ read_csv("_res/status_summary.csv", keep_default_na=False) }}


		=== "Pre-Certification"

		When an account is in Pre-Certification status, all RCS services are accessible and action will be required soon.


		When an account is in Pre-Certification status, all RCS services are accessible and action will be required soon.

		?? days after entering Pre-Certification status, accounts will enter Certification status and action will be required. To prevent Certification status, you may certify at any time.


		?? days after entering Pre-Certification status, accounts will enter Certification status and action will be required. To prevent Certification status, you may certify at any time.

		While in Pre-Certification status, the [Account Status page](#how-do-i-check-my-rcs-account-status) will show "Account in Pre-Certification", as shown below.

Grids, Tabs, and Macros #1104

Are you sure you want to change the base?

Grids, Tabs, and Macros #1104

Uh oh!

Conversation

wwarriner commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Intent

Proposed Changes

Changes to Section Headers

Changes to Page URLs

Related or Fixed Issues

Accessibility Checklist

Style Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bdu-birhanu Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bdu-birhanu Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wwarriner commented Oct 29, 2025 •

edited

Loading

bdu-birhanu Nov 18, 2025 •

edited

Loading

bdu-birhanu Nov 18, 2025 •

edited

Loading