Merge pull request #36 from osg-htc/feat/persona-site-management

feat(site): web-site-management doc, persona CSS & banners, jinja partial

Author: ShawnMcKee

docs/css/extra.css

@@ -102,3 +102,24 @@ background-color: #1f2326;
 .md-nav__source {
 background-color: #1f2326;
 }
+
+/* Persona banner styles */
+.persona-banner {
+  border-left: 4px solid #2E86AB;
+  background-color: #f4f8fb;
+  padding: 12px 16px;
+  margin: 12px 0 18px 0;
+  border-radius: 4px;
+}
+.persona-banner .title {
+  font-weight: 600;
+  color: #1b3765;
+  margin: 0 0 4px 0;
+}
+.persona-banner .meta {
+  font-size: 0.9rem;
+  color: #244358;
+}
+.persona-quick-deploy { border-left-color: #2E86AB; }
+.persona-troubleshoot { border-left-color: #E07A5F; }
+.persona-research { border-left-color: #9B59B6; }

docs/personas/quick-deploy/landing.md

@@ -14,6 +14,10 @@ tags: [quickstart, perfSONAR, testpoint]
 ---
 
 # Quick Deploy — perfSONAR Testpoint
+<div class="persona-banner persona-quick-deploy">
+	<p class="title">Quick Deploy</p>
+	<p class="meta">Owners: networking-team@osg-htc.org</p>
+</div>
 
 This landing page links to minimal, tested instructions and automation to get a perfSONAR testpoint running quickly.
 

docs/personas/research/landing.md

@@ -9,6 +9,11 @@ tags: [architecture, research]
 
 # Research — Architecture & Rationale
 
+<div class="persona-banner persona-research">
+	<p class="title">Researcher</p>
+	<p class="meta">Owners: networking-team@osg-htc.org</p>
+</div>
+
 This area is for readers who want to understand system architecture, data pipelines, and development notes. See `architecture.md` and `data-pipeline.md` for diagrams and ingestion details.
 
 Key pages:

docs/personas/troubleshoot/landing.md

@@ -10,6 +10,11 @@ tags: [troubleshoot, playbook]
 
 # Troubleshooter — Triage and Playbooks
 
+<div class="persona-banner persona-troubleshoot">
+	<p class="title">Troubleshooter</p>
+	<p class="meta">Owners: networking-team@osg-htc.org</p>
+</div>
+
 This landing page points you to triage checklists, playbooks, and common issue pages. Start with the triage checklist and follow the relevant playbook.
 
 - `triage-checklist-v2.md`

docs/web-site-management.md

@@ -0,0 +1,58 @@
+---
+title: Website Management & Ops
+description: Guidance for maintaining the OSG networking site and personae workflow
+---
+
+# Website Management & Operations
+
+This page outlines recommended processes for building, publishing and managing the OSG Networking site (MkDocs) with a focus on persona-based documentation. The goal is to maintain `docs/` as the single source of truth and manage generated `site/` through CI.
+
+## Overview
+- Use `docs/` as canonical source of content.
+- Build & verify with `mkdocs build` locally or via CI.
+- Use CI to deploy to `gh-pages` or a hosted platform; avoid committing generated `site/` to the repo when possible.
+
+## Local development & testing
+1. Create a Python virtualenv and install dependencies:
+~~~bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install mkdocs mkdocs-material pymdown-extensions
+~~~
+2. Run a local preview server:
+~~~bash
+mkdocs serve -a 0.0.0.0:8000
+~~~
+3. Build the site for local verification:
+~~~bash
+mkdocs build --clean -d site
+~~~
+
+## CI & Publishing
+1. CI should run the following steps on PRs and pushes to `master`:
+   - `mkdocs build --clean` (fail on build errors)
+   - Run link checks and the `verify-site-scripts.sh` script to assert docs/site parity for changed files (optional if not keeping `site/` in repo)
+   - Run `autoupdate-scripts-sha.sh` to update `*.sha256` files when scripts change in docs.
+2. CI publish step (if you want to auto-deploy): use `peaceiris/actions-gh-pages` or `JamesIves/github-pages-deploy-action` to publish the `site/` directory to the `gh-pages` branch or a host.
+
+## Keep `docs/` canonical
+- Prefer editing and reviewing changes to files under `docs/`.
+- If you must edit `site/` (e.g., for manual content patches), follow the same review process and back-propagate changes into `docs/`.
+
+## Persona content & operational workflow
+- Persona pages live under `docs/personas/<persona>/` and should include the canonical `landing.md`, `intro.md`, and other materials.
+- Owners and status metadata should be included in frontmatter (owner email or team, status: proposed/draft/stable). This helps review and governance.
+
+## Actions we automated
+- CI verification: `.github/scripts/verify-site-scripts.sh` — verifies `docs/` script copies and `site/` parity for changed scripts.
+- Autoupdate: `.github/scripts/autoupdate-scripts-sha.sh` — updates per script `*.sha256` and `scripts.sha256` when a script in `docs/` changes in a PR.
+
+## Migration / Next steps
+1. Consider removing `site/` from the repo if CI deployment is configured and stable; commit `site/` removal with a PR that updates CI to publish built site to `gh-pages`.
+2. Add a `web-site-management.md` page (this page) with step-by-step instructions for maintainers.
+3. Add code owners for `docs/` and `personas` to ensure consistent review.
+
+---
+
+If anything in this workflow should be changed (e.g., we continue to check in site), we can adapt the CI accordingly to keep both the ease of `site/` updates and code reviewing safeguards.

mkdocs.yml

@@ -48,6 +48,7 @@ nav:
     - 'LS registration updater (script)': 'perfsonar/tools_scripts/perfSONAR-update-lsregistration.sh'
     - 'LS registration helpers (README)': 'perfsonar/tools_scripts/README-lsregistration.md'
     - 'Link-check tools': 'tools/README.md'
+    - 'Site management': 'web-site-management.md'
 
 markdown_extensions:
   - admonition

osgthedocs/partials/persona-banner.html

@@ -0,0 +1,9 @@
+{# Persona banner partial - Displays if page.meta.persona exists #}
+{% if page.meta.persona %}
+  <div class="persona-banner persona-{{ page.meta.persona | lower | replace(' ', '-') }}">
+    <p class="title">Persona: {{ page.meta.title or page.meta.persona }}</p>
+    {% if page.meta.owners %}
+    <p class="meta">Owners: {{ page.meta.owners | join(', ') }}</p>
+    {% endif %}
+  </div>
+{% endif %}