Initial commit

Garth Pickell · Copilot · Garth Pickell · commit 27ab5b70941a · 2026-06-08T22:02:58.000-07:00
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -0,0 +1,53 @@
+# Markdown Docs Reader
+
+This project is a lightweight markdown documentation viewer built for **large, code-heavy doc sets**. It uses Docsify as the rendering base, but the goal is not just to display markdown files in a browser. It is meant to make long-form technical documentation easier to navigate, easier to share at the exact right spot, and easier to copy from when the docs are full of code.
+
+Many markdown viewers are optimized for reading a single document. This one is optimized for reading a **documentation tree**: lots of files, deep navigation, heavy use of relative links, and pages that are revisited as reference material instead of read once from top to bottom.
+
+## Why this exists
+
+Standard markdown viewers usually do the basics well:
+
+- render markdown
+- show a sidebar or table of contents
+- apply a theme
+
+What they usually do *not* do well is support the workflow of someone moving through engineering docs all day. This reader adds behavior for that workflow:
+
+- keeping navigation in sync with where the reader actually is inside a page
+- making deep links useful beyond just the file level
+- treating code blocks as reusable working material, not just formatted text
+- preserving repository-style document structure instead of forcing docs into a separate publishing model
+
+## Advanced features
+
+| Feature | Why it matters |
+| --- | --- |
+| Scroll-synced deep links | The URL updates as the reader moves through headings, so a shared link can point to the actual section being read, not just the page. |
+| Sidebar state driven by reading position | The active navigation item follows the current section, which makes long pages and nested doc trees easier to stay oriented in. |
+| Compact nested navigation | Deeper sidebar levels stay collapsed until they are relevant, reducing noise in dense documentation sets. |
+| Segment-level code copy | Code blocks are broken into logical segments so readers can copy just the useful part of an example instead of manually selecting text. |
+| Full-snippet copy alongside partial copy | Readers can grab the whole block or a single segment depending on whether they want the complete example or just the command/code they need. |
+| Code-first visual treatment | Comments, spacing, and snippet boundaries are surfaced in a way that makes walkthrough-style documentation easier to scan. |
+| Repo-friendly relative path handling | The viewer works well with documentation that already lives in a repository and links relatively across folders. |
+| Static hosting simplicity | It stays easy to host and preview because it can be served from a basic static web server. |
+
+## Good fit
+
+This viewer is especially useful for:
+
+- internal engineering handbooks
+- SDK or platform docs
+- architecture and integration guides
+- code walkthroughs
+- versioned documentation sets
+
+## Development
+
+The [`studio-base`](./studio-base/README.md) folder is an example documentation set for developing and tuning the viewer.
+
+## Run
+
+```bash
+python -m http.server 4480
+```
diff --git a/plugin.js b/plugin.js
@@ -0,0 +1,296 @@
+var __init;
+__init();
+
+__init = function() {
+    let timer;
+    const list = [];
+    function scrolling(_, delay = 300) {
+        if (timer) {
+            clearTimeout(timer);
+        }
+
+        timer = setTimeout(function() {
+            timer = undefined;
+
+            let last = list[0];
+            const root = document.querySelector(".content");
+            const view = root.getBoundingClientRect(); 
+            const mid = (view.top + view.bottom) / 2;
+            for (const el of list) {
+                const rect = el.getBoundingClientRect();
+                if (rect.top > view.top - 3) {
+                    if (rect.top < mid) {
+                        last = el;
+                    }
+
+                    break;
+                }
+
+                last = el;
+            }
+
+            const id = last.id;
+            const hash = location.hash.replace(/\?.*/, "");
+            history.replaceState(null, null, `${hash}?id=${id}`);
+
+            const current = document.querySelector(".sidebar .active");
+            if (current) {
+                current.classList.remove("active");
+            }
+
+            for (const el of document.querySelectorAll(".sidebar a")) {
+                if (el.href === location.href) {
+                    el.parentElement.classList.add("active");
+                }
+            }
+        }, delay);
+    }
+
+    function scrollToPart() {
+        const hash = location.hash.replace(/.*\?/, "");
+        const args = new URLSearchParams(hash);
+        const id = args.get("id") || "_top";
+        const target = document.getElementById(id);
+        const scroller = document.querySelector(".content");
+        if (target) {
+            target.scrollIntoView({
+                block: "start",
+                behavior: "instant"
+            });
+
+            return;
+        }
+
+        scroller.scrollTo({
+            top: 0,
+            behavior: "instant"
+        });
+    }
+
+    addEventListener("hashchange", scrollToPart);
+
+    if (location.hash === "") {
+        history.replaceState(null, null, "#/home/README.md");
+    }
+
+    let cleanup;
+    function updateHash() {
+        if (cleanup) {
+            cleanup();
+        }        
+
+        const root = document.querySelector(".content");
+        root.addEventListener("scroll", scrolling, { passive: true });
+
+        cleanup = function() {
+            list.length = 0;
+            root.removeEventListener("scroll", scrolling);
+
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        };
+
+        for (const el of document.querySelectorAll(".content h1, .content h2, .content h3")) {
+            list.push(el);
+        }
+        
+        scrolling(null, 0);
+    }
+
+    function addCopyButtons() {
+        for (const pre of document.querySelectorAll(".content pre code")) {
+            let text = [];
+            let line = [];
+            let prefix = "";
+            const lines = [];
+            const walker = document.createTreeWalker(pre, NodeFilter.SHOW_ALL);
+            while (walker.nextNode()) {
+                const node = walker.currentNode;
+                if (node.parentNode === pre) {
+                    line.push(node);
+                }
+
+                if (node.nodeType === Node.TEXT_NODE) {
+                    if (prefix) {
+                        node.data = prefix + node.data;
+                        prefix = "";
+                    }
+
+                    const parts = node.data.split("\n");
+                    if (parts.length > 1) {
+                        prefix = parts.pop();
+                        node.data = parts.shift();
+                        text.push(node.data);
+
+                        lines.push([text.join(""), line]);
+
+                        for (const part of parts) {
+                            lines.push([part, [part]]);
+                        }
+
+                        text = [];
+                        line = [];
+                    }
+                    else {
+                        text.push(node.data);
+                    }
+                }
+            }
+
+            if (line.length > 0) {
+                lines.push([text.join(""), line]);
+            }
+
+            if (prefix) {
+                lines.push([prefix, [prefix]]);
+            }
+
+            const fullText = lines.map(function([text]) {
+                return text;
+            }).join("\n");
+
+            pre.innerHTML = "";
+
+            const fullCopy = document.createElement("button");
+            fullCopy.className = "copy-button full-copy-button";
+            fullCopy.dataset.label = "copy all";
+            fullCopy.addEventListener("click", function() {
+                navigator.clipboard.writeText(fullText);
+
+                const root = pre.parentElement;
+                root.classList.add("copying");
+                setTimeout(function() {
+                    root.classList.remove("copying");
+                }, 100);
+            });
+            pre.parentElement.append(fullCopy);
+
+            let group;
+            for (const [text, line] of lines) {
+                let comment = false;
+                let single = false;
+                let space = false;
+                let end = false;
+                if (text[0] === "#") {
+                    end = true;
+                    single = true;
+                    comment = true;
+                }
+
+                if (text.trim() === "") {
+                    end = true;
+                    single = true;
+                    space = true;
+                }
+
+                if (!space && text[0].trim()) {
+                    end = true;
+                }
+
+                if (group && end) {
+                    pre.append(group);
+                    group = undefined;
+                }
+
+                let first = false;
+                if (!group) {
+                    first = true;
+                    group = document.createElement("div");
+                    group.className = "code-segment";
+                }
+                else {
+                    group.append("\n");
+                }
+
+                if (comment) {
+                    group.className = "code-comment";
+                }
+                else if (space) {
+                    group.className = "code-space";
+                }
+
+                if (space) {
+                    group.append("\n");
+                }
+                else {
+                    for (const node of line) {
+                        group.append(node);
+                    }
+                }
+               
+                if (single) {
+                    pre.append(group);
+                    group = undefined;
+                }
+                else if (first) {
+                    const copy = document.createElement("button");
+                    copy.className = "copy-button";
+                    copy.dataset.label = "copy";
+                    group.append(copy);
+
+                    const which = group;
+                    copy.addEventListener("click", function() {
+                        const text = which.innerText;
+                        navigator.clipboard.writeText(text);
+
+                        which.classList.add("copying");
+                        setTimeout(function() {
+                            which.classList.remove("copying");
+                        }, 100);
+                    });
+                }
+            }
+
+            if (group) {
+                pre.append(group);
+            }
+        }
+    }
+
+    function fixLinks() {
+        const root = new URL(location.href);
+        root.hash = "";
+
+        for (const a of document.querySelectorAll("a")) {
+            const url = new URL(a.href);
+            const hash = url.hash.replace(/.*\?/, "");
+            const args = new URLSearchParams(hash);
+            url.hash = "";
+
+            if (root.href === url.href) {
+                args.delete("id");
+                
+                if (args.size) {
+                    a.href = "?" + args;
+                }
+            }
+        }
+    }
+
+    const config = window.$docsify || {};
+    const alias = config.alias || {};
+    const plugins = config.plugins || [];
+    window.$docsify = Object.assign(config, {
+        loadNavbar: true,
+        maxLevel: 3,
+        routerMode: "hash",
+        relativePath: true,
+        alias: {
+            ".*/_navbar.md": "_navbar.md",
+            ...alias,
+        },
+        plugins,
+    });
+
+    plugins.push(function(hook) {
+        hook.doneEach(scrollToPart);
+        hook.doneEach(updateHash);
+        hook.doneEach(addCopyButtons);
+        hook.doneEach(fixLinks);
+    });
+};
+
+__init();
+__init = undefined;
diff --git a/studio-base/README.md b/studio-base/README.md
@@ -0,0 +1 @@
+See [here](./)
diff --git a/studio-base/_navbar.md b/studio-base/_navbar.md
@@ -0,0 +1,4 @@
+[![](https://apps.vertigisstudio.com/favicon.ico) Studio Base](/home/README.md)
+[Tags and Versions](/home/docs/index.md)
+[Host Kit](/kit/README.md)
+[Utility Containers](/kit/utils/README.md)
diff --git a/studio-base/index.html b/studio-base/index.html
@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <link rel="icon" href="https://apps.vertigisstudio.com/favicon.ico">
+  <title>VertiGIS Studio Base</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="theme-color" content="#07131f">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css">
+  <link rel="stylesheet" href="../styles.css">
+</head>
+<body>
+    <div id="app"></div>
+
+    <script>
+        function __init() {
+            const args = new URL(location.href).searchParams;
+            const tag = args.get("tag") || "gh-pages";
+            window.$docsify = {
+                alias: {
+                    "/home/(.*)": `https://raw.githubusercontent.com/gpickell/studio-base/${tag}/$1`,
+                    "/kit/(.*)": "https://raw.githubusercontent.com/vertigis/host-kit/master/$1"
+                }
+            }
+        }
+    </script>
+    <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs/components/prism-yaml.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs/components/prism-docker.min.js"></script>
+    <script src="../plugin.js"></script>
+</body>
+</html>
diff --git a/styles.css b/styles.css
