Grids, Tabs, and Macros

.vscode/extensions.json

@@ -4,6 +4,7 @@
     "DavidAnson.vscode-markdownlint",
     "ms-python.python",
     "redhat.vscode-yaml",
+    "samuelcolvin.jinjahtml",
     "tamasfe.even-better-toml",
     "yzhang.markdown-all-in-one",
   ]

.vscode/settings.json

@@ -16,6 +16,15 @@
     "editor.wordWrap": "on",
     "files.eol": "\n"
   },
+  "[jinja-md]": {
+    "editor.defaultFormatter": "samuelcolvin.jinjahtml",
+    "editor.formatOnSave": true,
+    "editor.indentSize": 4,
+    "editor.insertSpaces": true,
+    "editor.tabSize": 4,
+    "editor.wordWrap": "on",
+    "files.eol": "\n"
+  },
   "[json]": {
     "editor.defaultFormatter": "vscode.json-language-features",
     "editor.formatOnSave": true,
@@ -90,12 +99,12 @@
     "editor.tabSize": 2,
     "files.eol": "\n"
   },
-  "files.insertFinalNewline": true,
-  "files.trimFinalNewlines": true,
-  "files.trimTrailingWhitespace": true,
   "files.exclude": {
     "**/node_modules/*": true
   },
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "files.trimTrailingWhitespace": true,
   "files.watcherExclude": {
     "**/node_modules/*": true
   },
@@ -107,5 +116,19 @@
   "markdown.extension.tableFormatter.enabled": false,
   "markdown.extension.toc.updateOnSave": false,
   "markdown.validate.unusedLinkDefinitions.enabled": "warning",
-  "redhat.telemetry.enabled": false
+  "redhat.telemetry.enabled": false,
+  "yaml.customTags": [
+    "!ENV scalar",
+    "!ENV sequence",
+    "!relative scalar",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
+    "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
+  ],
+  "yaml.schemas": {
+    "./res/.grid_cards_schema.yml": "/res/grid_cards.yml",
+    "./res/.announcements_schema.yml": "/res/announcements.yml"
+    // "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  }
 }

build_env.yml

@@ -3,18 +3,13 @@ dependencies:
   - conda-forge::click=8.2.1
   - conda-forge::jinja2=3.1.6
   - conda-forge::libffi=3.4.6
-  - conda-forge::markdown=3.8.0
   - conda-forge::markupsafe=3.0.2 # Not semver, be cautious
   - conda-forge::mergedeep=1.3.4
-  - conda-forge::mkdocs=1.6.1
-  - conda-forge::mkdocs-material=9.6.14
-  - conda-forge::mkdocs-material-extensions=1.3.1
   - conda-forge::numpy=2.2.6
   - conda-forge::pandas=2.3.0
   - conda-forge::pandoc=3.7.0.2
   - conda-forge::pip=25.1.1
   - conda-forge::pygments=2.19.1
-  - conda-forge::pymdown-extensions=10.15 # Not semver, be cautious
   - conda-forge::pypandoc=1.15
   - conda-forge::pyparsing=3.0.9
   - conda-forge::python=3.13.3
@@ -31,11 +26,17 @@ dependencies:
   - conda-forge::yaml=0.2.5
   - conda-forge::yamllint=1.37.1
   - pip:
+      - jinja2-workarounds==0.1.0
+      - markdown==3.8.0
       - mkdocs-gen-files==0.5.0
       - mkdocs-glightbox==0.3.7
       - mkdocs-git-revision-date-localized-plugin==1.2.6
+      - mkdocs-material==9.6.14
       - mkdocs-redirects==1.2.1
-      - mkdocs-table-reader-plugin==2.0.3
+      - mkdocs-table-reader-plugin==3.1.0
       - linkchecker==10.4.0
       - pre-commit==3.7.1
+      - pymdown-extensions==10.8.1 # Not semver, be cautious
+      - git+https://github.com/wwarriner/mkdocs-macros-plugin@d445c98dcc14ecae48ddf53b4758f3942ed706b8
+      - git+https://github.com/uabrc/mkdocs@888fd28f92a320352f63600c24635231a42e5fac # new
       - git+https://github.com/uabrc/mkdocs-title-casing-plugin.git@stable

docs/_macro/link.md.j2

@@ -0,0 +1,3 @@
+{% macro link(text, path) -%}
+[{{ text }}]({{ path | normalize_link }})
+{%- endmacro %}

docs/_macro/support.md.j2

@@ -0,0 +1,65 @@
+{% from "_macro/link.md.j2" import link %}
+
+{% macro contact_support_link() -%}
+{{ link("Contact Support", "help/support.md") }}
+{%- endmacro %}
+
+{% macro _header(title, level) -%}
+{% for i in range(level) -%}{{- "#" -}}{%- endfor %} {{ title }}
+{%- endmacro %}
+
+{% macro help_header(level) -%}
+{{ _header("Help", level) }}
+{%- endmacro %}
+
+{% macro support_card_email() -%}
+{{
+    renderer.render_cards(
+        cards.support.email,
+    )
+}}
+{%- endmacro %}
+
+{% macro support_card_office_hours() -%}
+{{
+    renderer.render_cards(
+        cards.support.office_hours,
+    )
+}}
+{%- endmacro %}
+
+{% macro support_card_servicenow() -%}
+{{
+    renderer.render_cards(
+        cards.support.servicenow,
+    )
+}}
+{%- endmacro %}
+
+{% macro support_card_statuscast() -%}
+{{
+    renderer.render_cards(
+        cards.support.statuscast,
+)
+}}
+{%- endmacro %}
+
+{% macro support_cards_direct() -%}
+{{
+    renderer.render_cards(
+        cards.support.email,
+        cards.support.office_hours,
+    )
+}}
+{%- endmacro %}
+
+{% macro support_cards_all() -%}
+{{
+    renderer.render_cards(
+        cards.support.email,
+        cards.support.office_hours,
+        cards.support.servicenow,
+        cards.support.statuscast,
+    )
+}}
+{%- endmacro %}

docs/_template/base_help_section.md.j2

@@ -0,0 +1,4 @@
+{% from "_macro/support.md.j2" import support_cards_direct, help_header with context %}
+{{ help_header(2) }}
+
+{{ support_cards_direct() }}

docs/_template/uab_employee_use_only.md.j2

@@ -0,0 +1,3 @@
+!!! note
+
+    These instructions are intended for use by UAB employees.

docs/account_management/res/user_responsibilities.csv → docs/account/_res/user_responsibilities.csv

@@ -1,5 +1,5 @@
-Category,User Group,Requirements,Responsibilities
-UAB Employees,UAB Campus and UAB Medicine Faculty/Staff and Postdocs,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).<br>For Lab PIs and Core Directors please refer [Lab PIs responsibilities](#lab-pis).
-UAB Students,All UAB Campus and UAB Medicine Students,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).
-External Collaborators,All sponsored by UAB Employee,Must be sponsored by UAB employee <br>Must have XIAS email address,Collaborators' Responsibility:<br>&nbsp;  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).<br>&nbsp;  - [Create a XIAS Guest Account](../account_management/xias/guest_instructions.md#create-account).<br> Sponsor's Responsibility:<br>&nbsp;  - Sponsor is accountable for collaborators actions on UAB systems.<br>&nbsp;  - Please refer to [external collaborators](./xias/index.md#external-collaborator-xias-accounts) page.
-<span id= 'lab-pis' >Lab PIs</span>,All Lab PIs and Core Directors,Must have an active BlazerID,Data Management and Storage:<br>&nbsp;  - Periodically check group membership is correct.<br>&nbsp;  - Periodically check access controls to directories/buckets are correct.<br>&nbsp;  - Moving unused data to LTS or external archival solutions.<br>&nbsp;  - Managing backup plans.<br>OpenStack Projects:<br>&nbsp;  - Periodically check group membership is correct.<br>&nbsp;  - Periodically check unused resources are released.<br>PIs are also responsible to:<br>&nbsp;  - Regularly reviewing membership permissions and access control.<br>&nbsp;  - Ensure students are aware about [FERPA-protected project metadata](https://www.uab.edu/registrar/ferpa/faculty-staff).<br>&nbsp;  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).
+Category,User Group,Requirements,Responsibilities
+UAB Employees,UAB Campus and UAB Medicine Faculty/Staff and Postdocs,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).<br>For Lab PIs and Core Directors please refer [Lab PIs responsibilities](#lab-pis).
+UAB Students,All UAB Campus and UAB Medicine Students,Must have an active BlazerID,[Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).
+External Collaborators,All sponsored by UAB Employee,Must be sponsored by UAB employee <br>Must have XIAS email address,Collaborators' Responsibility:<br>&nbsp;  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).<br>&nbsp;  - [Create a XIAS Guest Account](../account_management/xias/guest_instructions.md#create-account).<br> Sponsor's Responsibility:<br>&nbsp;  - Sponsor is accountable for collaborators actions on UAB systems.<br>&nbsp;  - Please refer to [external collaborators](./xias/index.md#external-collaborator-xias-accounts) page.
+<span id= 'lab-pis' >Lab PIs</span>,All Lab PIs and Core Directors,Must have an active BlazerID,Data Management and Storage:<br>&nbsp;  - Periodically check group membership is correct.<br>&nbsp;  - Periodically check access controls to directories/buckets are correct.<br>&nbsp;  - Moving unused data to LTS or external archival solutions.<br>&nbsp;  - Managing backup plans.<br>OpenStack Projects:<br>&nbsp;  - Periodically check group membership is correct.<br>&nbsp;  - Periodically check unused resources are released.<br>PIs are also responsible to:<br>&nbsp;  - Regularly reviewing membership permissions and access control.<br>&nbsp;  - Ensure students are aware about [FERPA-protected project metadata](https://www.uab.edu/registrar/ferpa/faculty-staff).<br>&nbsp;  - [Refer to All User Responsibilities](../account_management/index.md#all-users-responsibilities).

docs/account/_template/authorization.md.j2

@@ -0,0 +1,20 @@
+# Research Computing System (RCS) Authorization
+
+## Who Is Eligible For RCS Authorization?
+
+Due to security requirements imposed by US federal funding agencies, RCS authorization is limited to specific UAB affiliations. If you are in one of the following categories, you are eligible to access RCS.
+
+- UAB Campus Employee
+- UAB Campus Student
+- UAB Medicine Employee
+- XIAS Guest with UAB Campus Employee Sponsor
+
+Other affiliations, including alumni and volunteer, are not authorized to access RCS.
+
+## What Else Is Required for RCS Authorization?
+
+Being in one of the categories above is necessary for RCS authorization, but not sufficient. Researchers are also expected to adhere to all relevant and prevailing policies, regulations, and laws, at all times.
+
+## Where Can I Read More About Policies?
+
+LINK GOES HERE

docs/account/_template/first_time_2fa.md.j2

@@ -0,0 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
+!!! security
+
+    If this is your first time logging in, you will first need to setup [Two-Factor Authentication](https://www.uab.edu/it/home/security/2-factor).

docs/account/_template/first_time_vpn.md.j2

@@ -0,0 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
+!!! security
+
+    If this is your first time logging in, you will first need to setup [UAB Campus Network VPN Access](https://www.uab.edu/it/home/tech-solutions/network/vpn). VPN access requires [Two-Factor Authentication](https://www.uab.edu/it/home/security/2-factor).

docs/account/_template/not_affiliated_with_uab.md.j2

@@ -0,0 +1,2 @@
+{% from "_macro/link.md.j2" import link %}
+Not affiliated with UAB? To access RCS, you must first {{ link("Create an External Collaborator (XIAS) Account", "account/xias/index.md") }}.

docs/account/_template/responsibilities_for_all.md.j2

@@ -0,0 +1,4 @@
+- Adherence to [UAB IT policies](https://www.uab.edu/it/home/policies).
+- Adherence to research data security requirements, when applicable (e.g., NIST 800-171, HIPAA, etc.)
+- [Responsible Conduct of Research (RCR) training](https://www.uab.edu/research/home/responsible-conduct-of-research) completed.
+- Fair and appropriate use of RCS platforms and services.

docs/account/_template/responsibilities_security.md.j2

@@ -0,0 +1,4 @@
+- Research data security
+    - Awareness, understanding, and application of relevant security standards, e.g., NIST 800-171, HIPAA, FERPA, etc.
+    - Know which requirements apply to each of your grants.
+    - Manage administrative controls for members of shared allocations.

docs/account/_template/uab_medicine_credentials.md.j2

@@ -0,0 +1,3 @@
+!!! important
+
+    UAB Medicine employees must authenticate with their BlazerID credentials. These are different from your UAB Medicine credentials.

docs/account/_template/xias_need_sponsor.md.j2

@@ -0,0 +1,3 @@
+!!! important
+
+    All researchers creating and using XIAS accounts must have a UAB employed sponsor.

docs/account/code.rc/create.md

@@ -0,0 +1,74 @@
+---
+hide:
+    toc: true
+---
+
+# Create Your Code.rc (GitLab) Account
+
+**Code.rc** is an on-premises GitLab server running on UAB IT infrastructure, administered by Research Computing, and part of the Research Computing System (RCS).
+
+Creating a Code.rc account is an automated, self-service process for researchers affiliated with UAB. External collaborators follow a different process.
+
+## What Do I Need Before Starting?
+
+Before starting, you'll need the following prerequisites.
+
+- An [RCS Account](../rcs/index.md) in [Good Standing](../rcs/status.md#what-are-the-possible-statuses-good-standing-ok).
+
+## How Do I Create a Code.rc Account?
+
+Please select the tab that best described your affiliation to UAB to see instructions for creating a Code.rc account.
+
+<!-- markdownlint-disable MD046 -->
+=== "UAB Campus & UAB Medicine"
+
+    Please select the LDAP tab and authenticate with your BlazerID credentials.
+
+    {% include "account/_template/uab_medicine_credentials.md.j2" indent content %}
+
+    ![!screenshot of code.rc login pane with ldap tab selected](_img/gitlab_researcher_ldap.png)
+
+=== "External Collaborator (XIAS)"
+
+    1. Ensure that your sponsor has included `https://code.rc.uab.edu` in the list of [approved URIs](../xias/1_sponsor_manage_sites.md) on the XIAS Site configuration page.
+
+        !!! important
+
+            XIAS account researchers will only be granted access if their sponsor adds the Code.rc URI to the list of approved URIs.
+
+    1. Have your sponsor send a request to <support@listserv.uab.edu> for a Code.rc account for their XIAS Guest. Please have the sponsor use the following template.
+
+    ```text
+    I hereby request a Code.rc account created for a XIAS account, and affirm that the external collaborator has an RCS account in good standing.
+
+    XIAS full name: _____
+    XIAS email address: _____
+    ```
+
+    1. UAB Research Computing will create an account.
+    1. You will receive an automated email from `donotreply.rc.code@uab.edu` with a link to create a password.
+    1. Follow the link to create a password for your account.
+    1. Navigate to <https://code.rc.uab.edu> to authenticate.
+    1. Select the Standard tab and authenticate with your XIAS credentials. Only use the `name` portion of your XIAS email address `name@domain.tld`. Do not include the `@` symbol or anything after. Use the password you created in the previous steps.
+
+        > Username or primary email: `name`
+        >
+        > Password: `********`
+
+        ![!screenshot of code.rc login pane with standard tab selected](_img/gitlab_researcher_standard.png)
+
+    1. Click `Sign in` to authenticate.
+
+=== "Unaffiliated"
+
+    {% include "account/_template/not_affiliated_with_uab.md.j2" indent content%}
+
+    {% include "account/_template/xias_need_sponsor.md.j2" indent content %}
+<!-- markdownlint-enable MD046 -->
+
+## Next Steps
+
+Now that your Code.rc (GitLab) account is created, learn more about how to use GitLab effectively.
+
+- [Official GitLab Tutorials](https://docs.gitlab.com/tutorials/)
+- [Code.rc](../../code.rc/index.md)

docs/account/code.rc/index.md

@@ -0,0 +1,26 @@
+---
+hide:
+    toc: true
+---
+
+# Create and Manage Code.rc (GitLab) Accounts
+
+UAB Research Computing maintains an on-premises GitLab server, part of the Research Computing System (RCS), called **Code.rc**. Generally speaking, [GitLab](https://about.gitlab.com/) is a service designed for collaborating on software development projects and is similar in structure and purpose to [GitHub](https://github.com/). In contrast to the Git hosting services [GitLab.com](https://gitlab.com) and [GitHub.com](https://github.com), Code.rc is hosted on-premises and stored in a secure physical environment on UAB Campus.
+
+<!-- markdownlint-disable MD046 -->
+!!! important
+
+    Code.rc accounts are managed separately from [Research Computing System (RCS) accounts](../rcs/index.md). Before creating a Code.rc account, you must create an RCS account.
+<!-- markdownlint-enable MD046 -->
+
+{{
+    renderer.render_cards(
+        cards.account.code_rc_create
+    )
+}}
+
+## Where Can I Find Code.rc?
+
+Code.rc may be found at <https://code.rc.uab.edu>.
+
+{% include "_template/base_help_section.md.j2" %}

docs/account/code.rc/manage.md

@@ -0,0 +1,40 @@
+---
+hide:
+    toc: true
+---
+
+# Managing Code.rc (GitLab) Accounts
+
+You can manage your Code.rc (GitLab) account by navigating to the web interface at <https://code.rc.uab.edu> and checking your User Profile. Within Code.rc, you can create and manage Groups and Projects, including which other Users and Groups have access, and what level of access, by assigning Roles.
+
+## What Do I Need to Get Started?
+
+Before starting, you'll need the following prerequisites.
+
+- A [Code.rc Account](./index.md).
+
+## How Do I View User Profiles?
+
+To view a profile, including your own:
+
+- Visit `https://code.rc.uab.edu/your-username`.
+- _or_
+    1. Login to <https://code.rc.uab.edu>.
+    1. Click your profile picture at the top of the left-hand sidebar. On narrow displays, the sidebar may be hidden. If so, click the "Show Sidebar" icon at the top-left of any page.
+    1. A pop-up menu will appear.
+    1. Click your name at the top of the pop-up menu.
+
+## How Do I Edit My User Profile?
+
+To edit your profile:
+
+- Visit <https://code.rc.uab.edu/-/user_settings/profile>.
+- _or_ [View Your Profile](#how-do-i-view-user-profiles), except instead of clicking your name at the last step, click "Edit Profile".
+
+## What Can Be Edited on My User Profile?
+
+You can change your profile picture, name, social media links, and bio in your user profile page.
+
+Please see the [Official GitLab Documentation](https://docs.gitlab.com/user/profile/) for more details.
+
+{% include "_template/base_help_section.md.j2" %}