feat: live preview rebuild, SharePoint video macro, CMS OAuth + preview styling

oto-macenauer · claude · oto-macenauer · commit f2a3610f7535 · 2026-06-15T23:46:59.000+02:00
- run.js --preview: watch source + auto-rebuild dist so CMS/local edits
  (incl. uploaded media) appear without a manual rebuild
- pack.py: add --no-package flag for fast watch rebuilds
- mkdocs-macros-plugin + main.py sharepoint_video() macro for embedding
  SharePoint/Stream videos in Markdown docs
- admin/config.yml: relative public_folder (base-path-safe media) and
  Cloudflare Worker OAuth (base_url + auth_endpoint)
- admin/index.html: register theme CSS + #docs-root/.prose wrapper so the
  docs preview matches the published theme

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/admin/config.yml b/admin/config.yml
@@ -8,11 +8,21 @@ backend:
   name: github
   repo: AbsaOSS/knowledge-base-docs-example
   branch: master
+  # OAuth handled by a Cloudflare Worker (sveltia-cms-auth). base_url overrides
+  # Decap's default Netlify OAuth host; auth_endpoint matches the Worker's /auth
+  # route. The Worker holds the GitHub OAuth client secret.
+  base_url: https://sveltia-cms-auth.kb-cms.workers.dev
+  auth_endpoint: auth
 
 # local_backend: true  # uncomment for local dev (run: npx decap-server)
 
+# media_folder = where uploads are committed in the repo.
+# public_folder = the path written into Markdown. Keep it RELATIVE (no leading
+# slash) so images resolve regardless of where the site is served — e.g. a
+# GitHub *project* page under /<repo>/ where an absolute "/docs/..." would 404.
+# MkDocs rewrites this relative path correctly for each page's output URL.
 media_folder: docs/assets/images
-public_folder: /docs/assets/images
+public_folder: assets/images
 
 # ── Documentation pages ──────────────────────────────────────────────────────
 # Folder collection: editors can create, edit, and delete pages in docs/.
diff --git a/admin/index.html b/admin/index.html
@@ -8,9 +8,37 @@
 <body>
   <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
   <script>
-    // ── Live preview for the showcase page ──────────────────────────────────
+    // ── Preview styles ───────────────────────────────────────────────────────
+    // Inject the built site CSS into the CMS preview iframe so the docs preview
+    // matches the published theme. style.css is the theme's pre-built Tailwind
+    // (incl. .prose typography); served at /docs/style.css on the built site.
+    CMS.registerPreviewStyle('/docs/style.css');
     CMS.registerPreviewStyle('/showcase.css');
 
+    // ── Live preview for documentation pages ────────────────────────────────
+    // The theme styles are scoped to "#docs-root" and ".prose" (see theme/
+    // main.html), so mirror that wrapper here or the markdown renders unstyled.
+    var DocsPreview = createClass({
+      render: function () {
+        return h(
+          'div',
+          { id: 'docs-root' },
+          h(
+            'main',
+            { id: 'content' },
+            h(
+              'article',
+              { className: 'prose prose-gray max-w-none', style: { padding: '1.5rem' } },
+              this.props.widgetFor('body')
+            )
+          )
+        );
+      }
+    });
+
+    CMS.registerPreviewTemplate('docs', DocsPreview);
+
+    // ── Live preview for the showcase page ──────────────────────────────────
     var ShowcasePreview = createClass({
       render: function () {
         var content = this.props.entry.getIn(['data', 'content']) || '';
diff --git a/docs/adding-pages.md b/docs/adding-pages.md
@@ -75,6 +75,39 @@ From the showcase HTML, link into the docs:
 <a href="docs/index.html">Read the docs</a>
 ```
 
+## Embedding SharePoint videos
+
+MkDocs renders Markdown, not MDX — but reusable components are available through
+[mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io/). Call the
+`sharepoint_video` macro from any `.md` page to drop in a responsive video:
+
+```markdown
+{% raw %}{{ sharepoint_video('https://absa.sharepoint.com/.../video.mp4', title='Onboarding demo') }}{% endraw %}
+```
+
+This renders a responsive 16:9 iframe that scales with the page. Arguments:
+
+| Argument | Required | Notes |
+|---|---|---|
+| `url` | Yes | SharePoint share/embed URL. In SharePoint use **Share → Embed** and copy the `src`; a plain share link usually works too (append `&embed=true` if the player does not load). |
+| `title` | No | Accessible label for screen readers. |
+| `ratio` | No | Aspect-ratio padding. `"56.25%"` = 16:9 (default), `"75%"` = 4:3. |
+
+Macros are defined in `main.py` at the repo root — add your own there to build
+more reusable components.
+
+## Adding images
+
+Upload images through the CMS at `/admin/`, or drop files into
+`docs/assets/images/` and reference them with a path relative to your page:
+
+```markdown
+![Architecture diagram](assets/images/diagram.png)
+```
+
+MkDocs rewrites the path to the correct URL at build time, so it works both
+locally and when the site is served under a subpath.
+
 ## Cross-linking between Markdown pages
 
 Use relative paths without the `.md` extension in links:
diff --git a/main.py b/main.py
@@ -0,0 +1,59 @@
+#
+# Copyright 2026 ABSA Group Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""mkdocs-macros module — reusable components for documentation pages.
+
+Macros are usable directly inside any docs/*.md file, e.g.:
+
+    {{ sharepoint_video('https://absa.sharepoint.com/.../video.mp4', title='Demo') }}
+
+Docs: https://mkdocs-macros-plugin.readthedocs.io/
+"""
+
+import html
+
+
+def define_env(env):
+    """Register macros with the mkdocs-macros plugin."""
+
+    @env.macro
+    def sharepoint_video(url, title="SharePoint video", ratio="56.25%"):
+        """Embed a SharePoint / Microsoft Stream video as a responsive iframe.
+
+        Args:
+            url:   The SharePoint share/embed URL of the video.
+            title: Accessible iframe title (shown to screen readers).
+            ratio: Aspect-ratio padding. "56.25%" = 16:9, "75%" = 4:3.
+
+        Usage in a .md page:
+            {{ sharepoint_video('https://absa.sharepoint.com/.../video.mp4') }}
+
+        Tip: in SharePoint use "Share" → "Embed" and paste the src URL. A plain
+        share link usually works too; append "&embed=true" if the player does
+        not load.
+        """
+        safe_url = html.escape(str(url), quote=True)
+        safe_title = html.escape(str(title), quote=True)
+        return (
+            f'<div class="sp-embed" style="position:relative;width:100%;'
+            f'padding-bottom:{ratio};height:0;overflow:hidden;margin:1.5rem 0;'
+            f'border-radius:8px;background:#000;">'
+            f'<iframe src="{safe_url}" title="{safe_title}" '
+            f'style="position:absolute;top:0;left:0;width:100%;height:100%;border:0;" '
+            f'allowfullscreen '
+            f'allow="autoplay; fullscreen; encrypted-media; picture-in-picture" '
+            f'loading="lazy"></iframe></div>'
+        )
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -24,3 +24,8 @@ theme:
   custom_dir: theme
 
 # nav is auto-generated from frontmatter (title, order, section) by pack.py
+
+plugins:
+  - search
+  - macros:        # reusable components for docs pages — see main.py
+      module_name: main
diff --git a/requirements.txt b/requirements.txt
@@ -1,2 +1,3 @@
 mkdocs==1.6.1
 jinja2>=3.1
+mkdocs-macros-plugin>=1.0
diff --git a/run.js b/run.js
@@ -15,8 +15,9 @@
  * limitations under the License.
  */
 
-const { execFileSync, execSync } = require("child_process");
+const { execFileSync, execSync, spawn } = require("child_process");
 const { resolve } = require("path");
+const fs = require("fs");
 
 const ROOT = resolve(__dirname);
 const env = { ...process.env, PYTHONIOENCODING: "utf-8" };
@@ -48,13 +49,91 @@ function build(extraArgs) {
 }
 
 if (args.includes("--preview")) {
+  // Full build once, then serve dist/ AND watch source files so edits made by
+  // hand or through the CMS at /admin/ (incl. uploaded media) are picked up and
+  // dist/ is rebuilt automatically — no manual rebuild needed.
   build([]);
+
   console.log("\nServing dist/ at http://localhost:8000 …");
-  execFileSync(py, ["-m", "http.server", "8000", "-d", "dist"], {
+  const server = spawn(py, ["-m", "http.server", "8000", "-d", "dist"], {
     cwd: ROOT,
     stdio: "inherit",
     env,
   });
+
+  // Source paths that feed the build. dist/ is deliberately NOT watched (would
+  // loop). mkdocs-build*.yml are transient and live at the repo root, unwatched.
+  const watchTargets = [
+    "docs",
+    "data",
+    "theme",
+    "admin",
+    "mkdocs.yml",
+    "mkdocs-headless.yml",
+    "showcase.html",
+    "showcase.css",
+    "main.py",
+    "marketplace.json",
+  ];
+
+  let rebuilding = false;
+  let pending = false;
+  let timer = null;
+
+  function rebuild() {
+    if (rebuilding) {
+      pending = true;
+      return;
+    }
+    rebuilding = true;
+    console.log("\n↻ Change detected — rebuilding dist/ …");
+    try {
+      execFileSync(py, ["scripts/pack.py", "--no-package"], {
+        cwd: ROOT,
+        stdio: "inherit",
+        env: { ...env, SKIP_PIP_INSTALL: "1" },
+      });
+      console.log("✅ Rebuild complete — refresh your browser.\n");
+    } catch (e) {
+      console.error("⚠ Rebuild failed:", e.status || e.message);
+    }
+    rebuilding = false;
+    if (pending) {
+      pending = false;
+      schedule();
+    }
+  }
+
+  function schedule() {
+    clearTimeout(timer);
+    timer = setTimeout(rebuild, 300); // debounce bursty CMS/file writes
+  }
+
+  const watchers = [];
+  for (const target of watchTargets) {
+    const p = resolve(ROOT, target);
+    if (!fs.existsSync(p)) continue;
+    try {
+      watchers.push(fs.watch(p, { recursive: true }, schedule));
+    } catch {
+      // recursive watch unsupported (older Node on Linux) — watch shallowly
+      watchers.push(fs.watch(p, {}, schedule));
+    }
+  }
+  console.log(`Watching ${watchers.length} source path(s) — Ctrl+C to stop.`);
+
+  function shutdown() {
+    for (const w of watchers) {
+      try {
+        w.close();
+      } catch {}
+    }
+    if (server && !server.killed) server.kill();
+    process.exit(0);
+  }
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  server.on("exit", (code) => process.exit(code || 0));
 } else if (args.includes("--dev")) {
   try {
     execFileSync(py, ["scripts/pack.py", "--serve"], {
diff --git a/scripts/pack.py b/scripts/pack.py
@@ -242,11 +242,14 @@ def add_entries(items, section=None):
 def main():
     headless = False
     serve = False
+    no_package = False
     for arg in sys.argv[1:]:
         if arg == "--headless":
             headless = True
         elif arg == "--serve":
             serve = True
+        elif arg == "--no-package":
+            no_package = True
         else:
             print(f"Unknown argument: {arg}")
             sys.exit(1)
@@ -282,6 +285,10 @@ def main():
         print("▶ Generating dist/marketplace.json with pages manifest...")
         generate_marketplace_json()
 
+        if no_package:
+            print("✅ dist/ rebuilt (headless, packaging skipped)")
+            return
+
         print("▶ Packaging (headless)...")
         with tarfile.open("dist.tar.gz", "w:gz") as tar:
             tar.add("dist")
@@ -306,6 +313,10 @@ def main():
         print("▶ Generating dist/marketplace.json with pages manifest...")
         generate_marketplace_json()
 
+        if no_package:
+            print("✅ dist/ rebuilt (packaging skipped)")
+            return
+
         print("▶ Packaging...")
         with tarfile.open("dist.tar.gz", "w:gz") as tar:
             tar.add("dist")

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`mkdocs==1.6.1`
`2`	`2`	`jinja2>=3.1`
	`3`	`+mkdocs-macros-plugin>=1.0`