MSD-LIVE · msdlive-admin · Jul 24, 2026 · Jun 16, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -1,9 +1,11 @@
-name: Deploy MkDocs (Docs + Embed)
+name: Deploy MkDocs
 
 on:
     push:
-        branches:
-            - main
+        branches: ['**']          # build previews from every branch
+    pull_request:
+        branches: [main]           # validate PRs targeting main
+    workflow_dispatch:             # manual, any branch
 
 permissions:
     contents: read
@@ -12,48 +14,43 @@ permissions:
 
 concurrency:
     group: "pages"
-    cancel-in-progress: true
+    cancel-in-progress: false
 
 jobs:
     build:
         runs-on: ubuntu-latest
-
         steps:
-            - name: Checkout
-              uses: actions/checkout@v4
+            - uses: actions/checkout@v4
 
-            - name: Set up Python
-              uses: actions/setup-python@v5
+            - uses: actions/setup-python@v5
               with:
-                  python-version: "3.11"
+                  python-version: "3.12"
+                  cache: "pip"
+                  cache-dependency-path: requirements.txt
 
             - name: Install dependencies
-              run: |
-                  pip install -r requirements.txt
+              run: pip install -r requirements.txt
 
-            - name: Build normal docs
-              run: |
-                  mkdocs build --strict
+            - name: Build docs
+              run: mkdocs build --strict
 
-            - name: Build embed (headless) docs
-              run: |
-                  mkdocs build \
-                    -f mkdocs.embed.yml \
-                    -d site/embed
+            - name: Build embed docs
+              run: mkdocs build --strict -f mkdocs.embed.yml -d site/embed
 
             - name: Upload Pages artifact
+              if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
               uses: actions/upload-pages-artifact@v3
               with:
                   path: site
 
     deploy:
         needs: build
+        if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
         runs-on: ubuntu-latest
         environment:
             name: github-pages
             url: ${{ steps.deployment.outputs.page_url }}
-
         steps:
             - name: Deploy to GitHub Pages
               id: deployment
-              uses: actions/deploy-pages@v4
+              uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -1,83 +1,145 @@
-# MSD-LIVE Docs (mkdocs)
+# MSD-LIVE Docs (MkDocs)
 
-A lightweight local workflow for previewing the MSD-LIVE documentation site built with MkDocs and the Material theme.
+Documentation site for MSD-LIVE, built with MkDocs and the Carbon theme. Deployed to GitHub Pages in **two forms**:
+
+- **Full docs** at `/` — standalone site with nav, header, search. Linked from the "Help" button in the landing page header.
+- **Headless embed** at `/embed/` — same content, chrome stripped, designed to be loaded inside iframes on the MSD-LIVE React landing page via the `DocsEmbed` component.
+
+Both are produced from the same Markdown sources; only the theme configuration and CSS differ.
 
 ## Prerequisites
 
-- Python 3.8+ (you have Python 3.12 available locally)
+- Python 3.8+ (Python 3.12 recommended)
 - pip
 - Recommended: create and use a virtual environment
 
 ## Quick Start (development)
 
 1. Create and activate a virtual environment (optional but recommended):
 
-```bash
-python -m venv .venv
-source .venv/bin/activate
-```
+    ```bash
+    python -m venv .venv
+    source .venv/bin/activate
+    ```
 
 2. Install dependencies:
 
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+3. Run the development server (`--livereload` is required for WSL — otherwise file changes only appear after restarting):
+
+    ```bash
+    mkdocs serve --livereload
+    ```
+
+4. Open the site in your browser:
+
+    ```text
+    http://127.0.0.1:8000/
+    ```
+
+### Previewing the Embed Build Locally
+
+To preview the headless build used by iframes:
+
 ```bash
-pip install -r requirements.txt
+mkdocs serve --livereload -f mkdocs.embed.yml -a 127.0.0.1:8001
 ```
 
-3. Run the development server (--livereload is required for WSL otherwise changes to files only show up if you restart the serve command):
+Then open `http://127.0.0.1:8001/`.
+
+## Building for Production
+
+The two builds produce sibling directories under a single `site/` root:
 
 ```bash
-mkdocs serve --livereload
+# Full docs → site/
+mkdocs build --strict
+
+# Headless embed → site/embed/
+mkdocs build --strict -f mkdocs.embed.yml -d site/embed
 ```
 
-4. Open the site in your browser:
+Resulting layout:
 
-```text
-http://127.0.0.1:8000/
+```
+site/
+├── index.html                 ← full docs
+├── assets/
+├── platform_community/
+├── ...
+└── embed/                     ← headless docs (iframed by landing page)
+    ├── index.html
+    ├── platform_community/
+    └── ...
 ```
 
-## Troubleshooting
+Preview the combined output locally to mirror the GitHub Pages layout:
 
-- If the server doesn't reflect changes, stop and restart `mkdocs serve`.
+```bash
+python -m http.server 8001 --directory site
+```
 
-## Useful Links
+Visit:
+- `http://127.0.0.1:8001/` — full docs
+- `http://127.0.0.1:8001/embed/platform_community/about/` — a headless page as it would appear in an iframe
 
-- Project docs configuration: `mkdocs.yml`
-- Docs folder: `docs/`
+Deployment to GitHub Pages is handled automatically by `.github/workflows/deploy-docs.yml`:
+- Pushes to `main` → auto-deploy
+- Pushes to any branch → build-only (preview validation)
+- Pull requests targeting `main` → build-only
+- Manual `workflow_dispatch` from any branch → deploy (for feature-branch testing)
 
+## Project Structure
 
-Dev notes to sort out later:
+- `mkdocs.yml` — Main site configuration (nav, theme, plugins, extensions)
+- `mkdocs.embed.yml` — Headless configuration. Inherits from `mkdocs.yml` via `INHERIT:` and overrides the theme/CSS to strip nav, header, search, and footer
+- `docs/` — Markdown source files (shared between both builds)
+- `docs/styles/carbon-customizations.css` — Styling shared by both builds (card grids, layout patches, etc.)
+- `docs/styles/embed.css` — Additional styles applied only to the headless embed build (hides Carbon chrome)
+- `docs/overrides/` — Custom theme template overrides for the full build
+- `docs/overrides/embed/` — Custom theme template overrides for the headless build
+- `docs/javascripts/carbon-nav-scroll-fix.js` — Nav scroll behavior fix
+- `.github/workflows/deploy-docs.yml` — GitHub Pages deployment workflow (builds both `/` and `/embed/`, publishes as one artifact)
 
-# Production docs site
-https://msdlive-docs.readthedocs.io/
+## Embedding in the React Landing Page
 
+The landing page's `DocsEmbed` component loads pages from the **headless build** via iframe:
 
-To test running with sphinx build with:
-```bash
-sphinx-build -b html docs docs/_build/lhtm
 ```
-
-and run with
-```bash
-sphinx-autobuild docs docs/_build/html
+https://msd-live.github.io/msdlive-docs/embed/<path>/
 ```
 
+Routes like `/about`, `/policies`, and `/computational-resources` map to specific embed pages in `App.tsx`. The header's "Help" button links to the **full** docs site (not the embed) and opens in a new tab.
 
+Because both builds share the same Markdown sources, content changes are reflected in both contexts automatically after deployment. Only styling changes need to consider which build they target:
 
-Prefer mkdocs over sphinx because if we want to load the md files in our react landing page app, the sphinx pages will have sphinx only
-tags (like for the nav and TOC) where mkdocs all nav is defined in the yml. OR see if sphinx has better support for headleads rendering of 
-the built html
+- Add to `carbon-customizations.css` → affects both.
+- Add to `embed.css` → affects only the embed build.
+- Change theme templates → put them in `docs/overrides/` (full) or `docs/overrides/embed/` (headless).
 
-TODO for embedding in landing page:
+## Troubleshooting
 
-- 
-- identify what tags are for mkdocs only
+- **Dev server doesn't reflect changes** — stop and restart `mkdocs serve --livereload`.
+- **Embed page 404s in iframe but full docs page loads** — verify the page is included in `mkdocs.embed.yml`'s effective nav, and that `mkdocs build --strict -f mkdocs.embed.yml` succeeds locally.
+- **Embed styles look wrong** — check that `embed.css` is correctly hiding Carbon chrome (`cds-header`, `.md-sidebar--primary`, etc.). Load an embed URL directly in a browser (outside any iframe) to isolate the styling.
+- **`DocsEmbed` path mismatch** — the `path` prop in `App.tsx` routes must match the actual URL structure of the embed build (respecting `use_directory_urls`).
 
-Note:
-no longer will customize embedded video player as that was implemented in landing page app
+## Useful Links
 
+- Production docs: https://msd-live.github.io/msdlive-docs/
+- Production embed root: https://msd-live.github.io/msdlive-docs/embed/
+- MkDocs full config: `mkdocs.yml`
+- MkDocs embed config: `mkdocs.embed.yml`
 
-building html to embed in iframe on landing page:
-```
-mkdocs build -f mkdocs.embed.yml -d site-embed --clean
+---
+
+## Historical Notes
+
+**Why MkDocs over Sphinx?**
+Sphinx-generated HTML embeds Sphinx-specific tags for nav and TOC, making headless embedding harder. MkDocs defines navigation entirely in `mkdocs.yml`, which makes the rendered content cleaner and easier to embed in an iframe.
 
-```
+**Video player customization:**
+No longer handled here — implemented in the landing page app instead.
diff --git a/additional_pages/about.json b/additional_pages/about.json
@@ -569,7 +569,7 @@
                         {
                             "_uid": "2d331594-0333-4722-95ad-8f80dd3178c6",
                             "name": "Casey Burleyson",
-                            "role": "Principle Investigator",
+                            "role": "Principal Investigator",
                             "email": "",
                             "avatar": {
                                 "id": 820911,

diff --git a/docs/assets/avatars/Bekah_Mars.jpg b/docs/assets/avatars/Bekah_Mars.jpg
diff --git a/docs/assets/avatars/Carina_Lansing.jpg b/docs/assets/avatars/Carina_Lansing.jpg
diff --git a/docs/assets/avatars/Chandrika_Sivaramakrishnan.png b/docs/assets/avatars/Chandrika_Sivaramakrishnan.png
diff --git a/docs/assets/avatars/Jon_Weers.jpeg b/docs/assets/avatars/Jon_Weers.jpeg
diff --git a/docs/assets/avatars/Zoe_Guillen.jpg b/docs/assets/avatars/Zoe_Guillen.jpg
diff --git a/docs/assets/avatars/casey.png b/docs/assets/avatars/casey.png
diff --git a/docs/assets/icons/hand-holding-medical-solid-full.svg b/docs/assets/icons/hand-holding-medical-solid-full.svg
diff --git a/docs/assets/icons/head-side-virus-solid-full.svg b/docs/assets/icons/head-side-virus-solid-full.svg
diff --git a/docs/assets/icons/heart-pulse-solid-full.svg b/docs/assets/icons/heart-pulse-solid-full.svg
diff --git a/docs/assets/icons/laptop-code-solid-full.svg b/docs/assets/icons/laptop-code-solid-full.svg
diff --git a/docs/for_data_providers/create_example_notebooks.md b/docs/for_data_providers/create_example_notebooks.md
@@ -1,6 +1,6 @@
 ---
 include_from_chatbot: true
-noteboook_environment: notebook_lab 
+noteboook_environment: notebook_lab
 ---
 
 # Create Example Notebooks
@@ -12,7 +12,7 @@ Example notebooks (pre-packaged code) help users understand how to work with you
 If you prefer to build notebooks in your own environment, you can use your normal Git workflow:
 
 1. Clone your [linked GitHub notebook repository](setup_notebook_repository.md)
-2. Create or edit notebooks in your preferred local editor or IDE 
+2. Create or edit notebooks in your preferred local editor or IDE
 3. Test notebooks with your dataset
 4. Commit and push your changes to GitHub
 
@@ -42,10 +42,10 @@ Use [Notebook Lab](launch_notebook_environment.md) to create and test notebooks
 
 ## Writing Notebooks
 
-For detailed guidance on importing packages, accessing your data, and getting started with your analysis, see [Writing Notebooks](../../learning_resources/working_with_notebooks).
+For detailed guidance on importing packages, accessing your data, and getting started with your analysis, see [Writing Notebooks](../learning_resources/working_with_notebooks.md).
 
 > ### Best Practices
-> 
+>
 > - **Keep notebooks focused** — Create one notebook per analysis or workflow
 > - **Write clear explanations** — Use markdown cells and comments to explain each section
 > - **Include practical examples** — Show users how to subset, filter, and transform data

diff --git a/docs/for_data_users/create_notebook.md b/docs/for_data_users/create_notebook.md
@@ -19,10 +19,10 @@ When creating a new notebook, you need to choose where it will be stored. Your o
 - **/my_notebooks** — For your own temporary notebooks that you do not plan to share with others. Select this location when you want to explore the data privately for your own purposes.
 - **/notebooks** — For notebooks specific to this dataset that become an official, maintained part of the dataset materials (data validation, canonical analyses, examples the dataset should ship with). <span style="background-color: #fff3cd; padding: 2px 4px;">This option is only enabled if the dataset has a linked GitHub repository.</span>
 
-!!! warning 
+!!! warning
     All notebooks created will be deleted at the end of your notebook environment session. To persist your notebook, you can:
 
-    - Submit it as a pull request to the community or dataset owner 
+    - Submit it as a pull request to the community or dataset owner
     - Copy the notebook to your scratch directory so you can resume work in a subsequent session
     - Right-click and download the notebook to your local machine
 
@@ -34,4 +34,4 @@ Use this option when you want a faster starting point with package imports, data
 
 ## Writing Notebooks
 
-For detailed guidance on importing packages, accessing your data, and getting started with your analysis, see [Writing Notebooks](../../learning_resources/working_with_notebooks).
+For detailed guidance on importing packages, accessing your data, and getting started with your analysis, see [Writing Notebooks](../learning_resources/working_with_notebooks.md).
diff --git a/docs/for_data_users/use_scratch_directory.md b/docs/for_data_users/use_scratch_directory.md
@@ -51,13 +51,13 @@ To copy your processed/subsetted files to the scratch directory from within your
 
 5. Once complete, you'll receive a second notification confirming the copy finished
 
-> **Important:** 
+> **Important:**
     Using the "Copy to Scratch Dir" button in the file explorer is the preferred and supported way to copy files into your scratch directory. While it's technically possible to copy files using code inside notebooks, this is not recommended due to underlying S3 limitations.
 
 
 ## How to download files from the scratch directory
 
-For step-by-step instructions on downloading files from scratch with the msdlive CLI, see [Scratch directory usage in the msdlive CLI docs](../../tools_services/cli/usage/#scratch-directory).
+For step-by-step instructions on downloading files from scratch with the msdlive CLI, see [Scratch directory usage in the msdlive CLI docs](../tools_services/cli/usage.md#scratch-directory).
 
 
 ## Video Walkthrough
@@ -76,4 +76,3 @@ Watch this video for a walkthrough of copying files to the scratch directory and
 
 
 
-
diff --git a/docs/overrides/embed.html b/docs/overrides/embed.html
@@ -3,7 +3,8 @@
 
 <head>
     <meta charset="utf-8" />
-    <title>{{ page.title }}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{ page.title }} - MSD-LIVE Docs</title>
 
     {# MkDocs styles only #}
     {% for css in config.extra_css %}
@@ -14,7 +15,10 @@
 </head>
 
 <body class="docs-embed">
-    {{ page.content }}
+    <main id="main-content">
+        <a href="#main-content" class="skip-link">Skip to main content</a>
+        {{ page.content }}
+    </main>
 </body>
 
 </html>