mirror of
https://github.com/Stirling-Tools/Stirling-PDF.git
synced 2026-09-02 21:03:34 +03:00
Portal: add docs + auto-synced with full-text search (#6985)
# Description of Changes <!-- Please provide a summary of the changes, including: - What was changed - Why the change was made - Any challenges encountered Closes #(issue_number) --> --- ## Checklist ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### Translations (if applicable) - [ ] I ran [`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have run `task check` to verify linters, typechecks, and tests pass - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#7-testing) for more details.
This commit is contained in:
Anthony Stirling
@@ -0,0 +1,92 @@
|
||||
name: Sync Portal Docs
|
||||
|
||||
# Regenerates the portal Developer Docs manifest from the Stirling docs repo and
|
||||
# opens a PR when it changes. Runs weekly, on manual dispatch, or when the docs
|
||||
# repo fires a `docs-updated` repository_dispatch.
|
||||
on:
|
||||
schedule:
|
||||
- cron: "0 6 * * 1"
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
ref:
|
||||
description: "Docs repo ref (branch or tag) to sync from"
|
||||
required: false
|
||||
default: "main"
|
||||
repository_dispatch:
|
||||
types: [docs-updated]
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
name: Sync docs manifest
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
steps:
|
||||
- name: Harden Runner
|
||||
uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
|
||||
with:
|
||||
egress-policy: audit
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
||||
with:
|
||||
fetch-depth: 0
|
||||
persist-credentials: false
|
||||
|
||||
- name: Setup GitHub App Bot
|
||||
id: setup-bot
|
||||
uses: ./.github/actions/setup-bot
|
||||
with:
|
||||
app-id: ${{ secrets.GH_APP_ID }}
|
||||
private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
|
||||
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
|
||||
with:
|
||||
node-version: "22"
|
||||
cache: "npm"
|
||||
cache-dependency-path: frontend/package-lock.json
|
||||
|
||||
- name: Install frontend dependencies
|
||||
working-directory: frontend
|
||||
env:
|
||||
NPM_CONFIG_IGNORE_SCRIPTS: "true"
|
||||
run: npm ci --ignore-scripts --audit=false --fund=false
|
||||
|
||||
- name: Regenerate docs manifest
|
||||
working-directory: frontend
|
||||
env:
|
||||
DOCS_REF: ${{ github.event.inputs.ref || github.event.client_payload.ref || 'main' }}
|
||||
GITHUB_TOKEN: ${{ steps.setup-bot.outputs.token }}
|
||||
run: npm run docs:sync
|
||||
|
||||
- name: Create Pull Request
|
||||
id: cpr
|
||||
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
|
||||
with:
|
||||
token: ${{ steps.setup-bot.outputs.token }}
|
||||
commit-message: "Sync portal docs from docs repo"
|
||||
committer: ${{ steps.setup-bot.outputs.committer }}
|
||||
author: ${{ steps.setup-bot.outputs.committer }}
|
||||
signoff: true
|
||||
branch: sync-portal-docs
|
||||
base: main
|
||||
title: "Sync portal docs from docs repo"
|
||||
body: |
|
||||
Auto-generated by ${{ steps.setup-bot.outputs.app-slug }}[bot].
|
||||
|
||||
Regenerates `frontend/editor/src/portal/generated/docsManifest.json`
|
||||
from the Stirling docs repo via `npm run docs:sync`.
|
||||
labels: documentation,github-actions,frontend
|
||||
add-paths: frontend/editor/src/portal/generated/docsManifest.json
|
||||
delete-branch: true
|
||||
sign-commits: true
|
||||
@@ -12,6 +12,8 @@ editor/public/mockServiceWorker.js
|
||||
# Auto-generated OG/social-preview metadata (scripts/generate-og-metadata.mjs); regenerated verbatim.
|
||||
editor/public/og-metadata.json
|
||||
editor/src/core/data/ogImageMap.json
|
||||
# Auto-generated portal docs manifest (scripts/sync-portal-docs.mts); regenerated verbatim.
|
||||
editor/src/portal/generated/docsManifest.json
|
||||
editor/public/pdfjs*/
|
||||
editor/public/js/thirdParty/
|
||||
editor/public/css/cookieconsent.css
|
||||
|
||||
@@ -6534,6 +6534,10 @@ signature = "signature"
|
||||
beta = "Beta"
|
||||
ga = "GA"
|
||||
|
||||
[portal.docs]
|
||||
browse = "Browse docs"
|
||||
viewSource = "View source on GitHub"
|
||||
|
||||
[portal.docs.authentication]
|
||||
codeCaption = "every request"
|
||||
eyebrow = "GETTING STARTED"
|
||||
@@ -6619,11 +6623,19 @@ title = "Official SDKs"
|
||||
beta = "Beta"
|
||||
deprecated = "Deprecated"
|
||||
|
||||
[portal.docs.search]
|
||||
empty = "No matching docs"
|
||||
placeholder = "Search docs"
|
||||
results = "{{count}} results"
|
||||
|
||||
[portal.docs.skills]
|
||||
eyebrow = "SKILLS"
|
||||
lead = "Bundled, named capabilities your agent invokes as a single tool. Each skill is a deterministic op chain with evals attached."
|
||||
title = "Agent skills"
|
||||
|
||||
[portal.docs.toc]
|
||||
title = "On this page"
|
||||
|
||||
[portal.docs.webhooks]
|
||||
codeCaption = "document.processed"
|
||||
eyebrow = "API REFERENCE"
|
||||
@@ -7177,7 +7189,7 @@ storage = "Storage"
|
||||
[portal.nav]
|
||||
agent-builder = "Agent Builder"
|
||||
components = "Components"
|
||||
docs = "Developer Docs"
|
||||
docs = "Documentation"
|
||||
documents = "Documents"
|
||||
editor = "Editor"
|
||||
home = "Home"
|
||||
|
||||
@@ -6463,6 +6463,10 @@ bucket = "Bucket"
|
||||
name = "Name"
|
||||
region = "Region"
|
||||
|
||||
[portal.docs]
|
||||
browse = "Browse docs"
|
||||
viewSource = "View source on GitHub"
|
||||
|
||||
[portal.docs.authentication]
|
||||
codeCaption = "every request"
|
||||
eyebrow = "GETTING STARTED"
|
||||
@@ -6548,11 +6552,19 @@ title = "Official SDKs"
|
||||
beta = "Beta"
|
||||
deprecated = "Deprecated"
|
||||
|
||||
[portal.docs.search]
|
||||
empty = "No matching docs"
|
||||
placeholder = "Search docs"
|
||||
results = "{{count}} results"
|
||||
|
||||
[portal.docs.skills]
|
||||
eyebrow = "SKILLS"
|
||||
lead = "Bundled, named capabilities your agent invokes as a single tool. Each skill is a deterministic op chain with evals attached."
|
||||
title = "Agent skills"
|
||||
|
||||
[portal.docs.toc]
|
||||
title = "On this page"
|
||||
|
||||
[portal.docs.webhooks]
|
||||
codeCaption = "document.processed"
|
||||
eyebrow = "API REFERENCE"
|
||||
@@ -7217,7 +7229,7 @@ storage = "Storage"
|
||||
[portal.nav]
|
||||
agent-builder = "Agent Builder"
|
||||
components = "Components"
|
||||
docs = "Developer Docs"
|
||||
docs = "Documentation"
|
||||
documents = "Documents"
|
||||
editor = "Editor"
|
||||
home = "Home"
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
/**
|
||||
* Sync the portal Developer Docs from the Stirling docs repo.
|
||||
*
|
||||
* Fetches the docs repo tarball, extracts `docs/**` in-process (no external tar
|
||||
* binary, no per-file GitHub rate limits), shapes it with the pure transforms in
|
||||
* src/portal/docs/manifest/transform.ts, and writes the committed manifest that
|
||||
* the portal docs view renders. Re-run with `npm run docs:sync`.
|
||||
*
|
||||
* Env: DOCS_REPO, DOCS_REF, DOCS_ROOT override the defaults below.
|
||||
*/
|
||||
import { gunzipSync } from "node:zlib";
|
||||
import { mkdirSync, writeFileSync } from "node:fs";
|
||||
import { dirname, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
// tsx/node16 can't resolve the @portal alias here, so import by relative .ts path.
|
||||
// eslint-disable-next-line no-restricted-imports
|
||||
import {
|
||||
buildManifest,
|
||||
type CategoryMap,
|
||||
type RawDoc,
|
||||
} from "../src/portal/docs/manifest/transform.ts";
|
||||
|
||||
const REPO = process.env.DOCS_REPO ?? "Stirling-Tools/Stirling-Tools.github.io";
|
||||
const REF = process.env.DOCS_REF ?? "main";
|
||||
const ROOT = process.env.DOCS_ROOT ?? "docs";
|
||||
const SITE = "https://docs.stirlingpdf.com";
|
||||
|
||||
const HERE = dirname(fileURLToPath(import.meta.url));
|
||||
const OUT = resolve(HERE, "../src/portal/generated/docsManifest.json");
|
||||
|
||||
/* ── Minimal tar reader (ustar + pax/GNU long names) ─────────────────────── */
|
||||
|
||||
interface TarEntry {
|
||||
name: string;
|
||||
type: string;
|
||||
data: Buffer;
|
||||
}
|
||||
|
||||
function readTar(buf: Buffer): TarEntry[] {
|
||||
const entries: TarEntry[] = [];
|
||||
let offset = 0;
|
||||
let longName: string | null = null;
|
||||
let paxPath: string | null = null;
|
||||
|
||||
const str = (start: number, len: number) => {
|
||||
const slice = buf.subarray(start, start + len);
|
||||
const end = slice.indexOf(0);
|
||||
return slice.toString("utf8", 0, end === -1 ? len : end);
|
||||
};
|
||||
|
||||
while (offset + 512 <= buf.length) {
|
||||
const header = buf.subarray(offset, offset + 512);
|
||||
// Two consecutive zero blocks mark the end of the archive.
|
||||
if (header.every((b) => b === 0)) break;
|
||||
|
||||
const name = str(offset, 100);
|
||||
const prefix = str(offset + 345, 155);
|
||||
const sizeStr = str(offset + 124, 12).trim();
|
||||
const size = parseInt(sizeStr, 8) || 0;
|
||||
const type = String.fromCharCode(header[156]);
|
||||
const dataStart = offset + 512;
|
||||
const data = buf.subarray(dataStart, dataStart + size);
|
||||
|
||||
let fullName = prefix ? `${prefix}/${name}` : name;
|
||||
if (longName) {
|
||||
fullName = longName;
|
||||
longName = null;
|
||||
}
|
||||
if (paxPath) {
|
||||
fullName = paxPath;
|
||||
paxPath = null;
|
||||
}
|
||||
|
||||
if (type === "L") {
|
||||
// GNU long name: the payload is the real name of the next entry.
|
||||
longName = data.toString("utf8").replace(/\0+$/, "");
|
||||
} else if (type === "x") {
|
||||
// pax extended header: pull a `path=` record for the next entry.
|
||||
const record = /(?:^|\n)\d+ path=([^\n]+)\n/.exec(data.toString("utf8"));
|
||||
if (record) paxPath = record[1];
|
||||
} else if (type === "0" || type === "\0" || type === "") {
|
||||
entries.push({ name: fullName, type, data: Buffer.from(data) });
|
||||
}
|
||||
|
||||
offset = dataStart + Math.ceil(size / 512) * 512;
|
||||
}
|
||||
return entries;
|
||||
}
|
||||
|
||||
/* ── Fetch + shape ───────────────────────────────────────────────────────── */
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const url = `https://api.github.com/repos/${REPO}/tarball/${REF}`;
|
||||
console.log(`Fetching ${REPO}@${REF} …`);
|
||||
const res = await fetch(url, {
|
||||
headers: {
|
||||
Accept: "application/vnd.github+json",
|
||||
"User-Agent": "stirling-portal-docs-sync",
|
||||
...(process.env.GITHUB_TOKEN
|
||||
? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` }
|
||||
: {}),
|
||||
},
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw new Error(
|
||||
`GitHub tarball fetch failed: ${res.status} ${res.statusText}`,
|
||||
);
|
||||
}
|
||||
const gz = Buffer.from(await res.arrayBuffer());
|
||||
const entries = readTar(gunzipSync(gz));
|
||||
|
||||
// Strip the "<repo>-<sha>/" wrapper dir and keep only files under docs root.
|
||||
const prefix = `${ROOT}/`;
|
||||
const rawDocs: RawDoc[] = [];
|
||||
const categories: CategoryMap = {};
|
||||
for (const entry of entries) {
|
||||
const rel = entry.name.replace(/^[^/]+\//, "");
|
||||
if (!rel.startsWith(prefix)) continue;
|
||||
const inner = rel.slice(prefix.length);
|
||||
if (!inner) continue;
|
||||
if (inner.endsWith("/_category_.json")) {
|
||||
const dir = inner.slice(0, -"/_category_.json".length);
|
||||
try {
|
||||
categories[dir] = JSON.parse(entry.data.toString("utf8"));
|
||||
} catch {
|
||||
console.warn(` skipping unparseable _category_.json in ${dir}`);
|
||||
}
|
||||
} else if (/\.mdx?$/i.test(inner)) {
|
||||
rawDocs.push({ relPath: inner, content: entry.data.toString("utf8") });
|
||||
}
|
||||
}
|
||||
|
||||
if (rawDocs.length === 0) {
|
||||
throw new Error(`No markdown found under ${ROOT}/ — wrong repo/ref/root?`);
|
||||
}
|
||||
|
||||
const manifest = buildManifest(rawDocs, categories, {
|
||||
repo: REPO,
|
||||
ref: REF,
|
||||
root: ROOT,
|
||||
siteBaseUrl: SITE,
|
||||
});
|
||||
|
||||
mkdirSync(dirname(OUT), { recursive: true });
|
||||
writeFileSync(OUT, JSON.stringify(manifest, null, 2) + "\n", "utf8");
|
||||
|
||||
const items = manifest.nav.reduce((n, s) => n + s.items.length, 0);
|
||||
console.log(
|
||||
`Wrote ${manifest.nav.length} sections, ${items} docs → ${OUT.replace(/.*[/\\]frontend[/\\]/, "frontend/")}`,
|
||||
);
|
||||
for (const s of manifest.nav) {
|
||||
console.log(` ${s.icon} ${s.label} (${s.items.length})`);
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error(err instanceof Error ? err.message : err);
|
||||
process.exitCode = 1;
|
||||
});
|
||||
@@ -4,7 +4,9 @@
|
||||
"module": "node16",
|
||||
"moduleResolution": "node16",
|
||||
"types": ["node"],
|
||||
"noEmit": true
|
||||
"noEmit": true,
|
||||
// sync-portal-docs.mts imports the shared transform by its .ts path (run via tsx).
|
||||
"allowImportingTsExtensions": true
|
||||
},
|
||||
"include": ["./**/*.ts", "./**/*.mts"]
|
||||
}
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { lazy, Suspense } from "react";
|
||||
import { Navigate, Route, Routes } from "react-router-dom";
|
||||
import { Home } from "@portal/views/Home";
|
||||
import { Users } from "@portal/views/Users";
|
||||
@@ -11,10 +12,16 @@ import { Policies } from "@portal/views/Policies";
|
||||
import { EditorAdmin } from "@portal/views/EditorAdmin";
|
||||
import { Infrastructure } from "@portal/views/Infrastructure";
|
||||
import { PortalBillingGate } from "@portal/components/billing/PortalBillingGate";
|
||||
import { DeveloperDocs } from "@portal/views/DeveloperDocs";
|
||||
import { Procurement } from "@portal/views/Procurement";
|
||||
import { VIEW_PATHS, toPortalPath } from "@portal/contexts/ViewContext";
|
||||
|
||||
// Lazy so the generated docs manifest (bundled JSON) lands in its own chunk.
|
||||
const DeveloperDocs = lazy(() =>
|
||||
import("@portal/views/DeveloperDocs").then((m) => ({
|
||||
default: m.DeveloperDocs,
|
||||
})),
|
||||
);
|
||||
|
||||
// The portal mounts as a route-set under /processor/* in the editor app, so these
|
||||
// child routes are relative to that base: strip the leading slash from the
|
||||
// logical VIEW_PATHS, and home is the index route. Redirects use toPortalPath
|
||||
@@ -57,7 +64,14 @@ export function ViewRouter() {
|
||||
/>
|
||||
<Route path={rel(VIEW_PATHS.usage)} element={<PortalBillingGate />} />
|
||||
<Route path={rel(VIEW_PATHS.procurement)} element={<Procurement />} />
|
||||
<Route path={rel(VIEW_PATHS.docs)} element={<DeveloperDocs />} />
|
||||
<Route
|
||||
path={rel(VIEW_PATHS.docs)}
|
||||
element={
|
||||
<Suspense fallback={null}>
|
||||
<DeveloperDocs />
|
||||
</Suspense>
|
||||
}
|
||||
/>
|
||||
{/* Account-link is now a Settings panel; redirect legacy bookmarks home. */}
|
||||
<Route
|
||||
path="account-link"
|
||||
|
||||
@@ -1,8 +1,45 @@
|
||||
import { useEffect, useMemo, useRef, useState } from "react";
|
||||
import { Button, Skeleton, StatusBadge } from "@app/ui";
|
||||
import { useTranslation } from "react-i18next";
|
||||
import type { DocsNavSection } from "@portal/api/docs";
|
||||
|
||||
/** Left-hand documentation nav tree; each leaf selects an in-page section. */
|
||||
/**
|
||||
* Left-hand documentation nav: a hierarchical accordion. Section ids encode their
|
||||
* path ("functionality/security" is a child of "functionality"), so sub-sections
|
||||
* nest under their parent. The root "Overview" section is static (always open, no
|
||||
* toggle); every other section collapses, and only the branch leading to the
|
||||
* active doc opens by default. (Search lives in DocsSearch above this.)
|
||||
*/
|
||||
|
||||
// Matches the generator's ROOT_SECTION_ID: the intro section is never collapsible.
|
||||
const STATIC_SECTION_ID = "overview";
|
||||
|
||||
interface NavNode {
|
||||
section: DocsNavSection;
|
||||
children: NavNode[];
|
||||
}
|
||||
|
||||
/** Split "a/b/c" → "a/b"; null for a top-level id. */
|
||||
function parentId(id: string): string | null {
|
||||
const i = id.lastIndexOf("/");
|
||||
return i === -1 ? null : id.slice(0, i);
|
||||
}
|
||||
|
||||
/** Build the section tree from the flat, pre-sorted section list. */
|
||||
function buildTree(sections: DocsNavSection[]): NavNode[] {
|
||||
const byId = new Map<string, NavNode>(
|
||||
sections.map((s) => [s.id, { section: s, children: [] }]),
|
||||
);
|
||||
const roots: NavNode[] = [];
|
||||
for (const node of byId.values()) {
|
||||
const pid = parentId(node.section.id);
|
||||
const parent = pid ? byId.get(pid) : undefined;
|
||||
if (parent) parent.children.push(node);
|
||||
else roots.push(node);
|
||||
}
|
||||
return roots;
|
||||
}
|
||||
|
||||
export function DocsNav({
|
||||
sections,
|
||||
active,
|
||||
@@ -13,50 +50,125 @@ export function DocsNav({
|
||||
onSelect: (id: string) => void;
|
||||
}) {
|
||||
const { t } = useTranslation();
|
||||
// Per-section manual open/close, overriding the "active branch only" default.
|
||||
const [toggled, setToggled] = useState<Record<string, boolean>>({});
|
||||
const activeRef = useRef<HTMLButtonElement>(null);
|
||||
|
||||
const activeSectionId = useMemo(
|
||||
() => sections.find((s) => s.items.some((i) => i.id === active))?.id,
|
||||
[sections, active],
|
||||
);
|
||||
|
||||
const tree = useMemo(() => buildTree(sections), [sections]);
|
||||
|
||||
// Keep the active item in view when navigating (e.g. via a cross-link).
|
||||
useEffect(() => {
|
||||
activeRef.current?.scrollIntoView?.({ block: "nearest" });
|
||||
}, [active]);
|
||||
|
||||
const isOpen = (id: string): boolean => {
|
||||
if (id === STATIC_SECTION_ID) return true;
|
||||
// Default-open the branch containing the active doc (self or ancestor).
|
||||
const onActivePath =
|
||||
!!activeSectionId &&
|
||||
(activeSectionId === id || activeSectionId.startsWith(id + "/"));
|
||||
return toggled[id] ?? onActivePath;
|
||||
};
|
||||
|
||||
const renderNode = (node: NavNode) => {
|
||||
const { section, children } = node;
|
||||
const isStatic = section.id === STATIC_SECTION_ID;
|
||||
const open = isOpen(section.id);
|
||||
return (
|
||||
<div key={section.id} className="portal-docs__nav-group">
|
||||
{isStatic ? (
|
||||
<div className="portal-docs__nav-head">{section.label}</div>
|
||||
) : (
|
||||
<Button
|
||||
variant="tertiary"
|
||||
fullWidth
|
||||
justify="between"
|
||||
className="portal-docs__nav-head portal-docs__nav-head--button"
|
||||
aria-expanded={open}
|
||||
onClick={() =>
|
||||
setToggled((prev) => ({ ...prev, [section.id]: !open }))
|
||||
}
|
||||
rightSection={
|
||||
<span className="portal-docs__nav-count">
|
||||
{section.items.length}
|
||||
</span>
|
||||
}
|
||||
>
|
||||
<span className="portal-docs__nav-head-main">
|
||||
<span
|
||||
className={
|
||||
"portal-docs__nav-chevron" + (open ? " is-open" : "")
|
||||
}
|
||||
aria-hidden
|
||||
>
|
||||
▸
|
||||
</span>
|
||||
<span className="portal-docs__nav-headlabel">
|
||||
{section.label}
|
||||
</span>
|
||||
</span>
|
||||
</Button>
|
||||
)}
|
||||
|
||||
{open && (
|
||||
<>
|
||||
{section.items.length > 0 && (
|
||||
<ul className="portal-docs__nav-list">
|
||||
{section.items.map((item) => {
|
||||
const isActive = item.id === active;
|
||||
return (
|
||||
<li key={item.id}>
|
||||
<Button
|
||||
ref={isActive ? activeRef : undefined}
|
||||
variant="tertiary"
|
||||
justify="start"
|
||||
fullWidth
|
||||
className={
|
||||
"portal-docs__nav-link" +
|
||||
(isActive ? " is-active" : "")
|
||||
}
|
||||
aria-current={isActive ? "page" : undefined}
|
||||
onClick={() => onSelect(item.id)}
|
||||
>
|
||||
<span className="portal-docs__nav-label">
|
||||
{item.label}
|
||||
</span>
|
||||
{item.badge && (
|
||||
<StatusBadge
|
||||
tone={item.badge === "New" ? "success" : "info"}
|
||||
size="sm"
|
||||
>
|
||||
{item.badge}
|
||||
</StatusBadge>
|
||||
)}
|
||||
</Button>
|
||||
</li>
|
||||
);
|
||||
})}
|
||||
</ul>
|
||||
)}
|
||||
{children.length > 0 && (
|
||||
<div className="portal-docs__nav-children">
|
||||
{children.map(renderNode)}
|
||||
</div>
|
||||
)}
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
return (
|
||||
<nav
|
||||
className="portal-docs__nav"
|
||||
aria-label={t("portal.docs.nav.ariaLabel")}
|
||||
>
|
||||
{sections.map((section) => (
|
||||
<div key={section.id} className="portal-docs__nav-group">
|
||||
<div className="portal-docs__nav-head">
|
||||
<span className="portal-docs__nav-icon" aria-hidden>
|
||||
{section.icon}
|
||||
</span>
|
||||
{section.label}
|
||||
</div>
|
||||
<ul className="portal-docs__nav-list">
|
||||
{section.items.map((item) => {
|
||||
const isActive = item.id === active;
|
||||
return (
|
||||
<li key={item.id}>
|
||||
<Button
|
||||
variant="tertiary"
|
||||
justify="start"
|
||||
fullWidth
|
||||
className={
|
||||
"portal-docs__nav-link" + (isActive ? " is-active" : "")
|
||||
}
|
||||
aria-current={isActive ? "page" : undefined}
|
||||
onClick={() => onSelect(item.id)}
|
||||
>
|
||||
<span className="portal-docs__nav-label">{item.label}</span>
|
||||
{item.badge && (
|
||||
<StatusBadge
|
||||
tone={item.badge === "New" ? "success" : "info"}
|
||||
size="sm"
|
||||
>
|
||||
{item.badge}
|
||||
</StatusBadge>
|
||||
)}
|
||||
</Button>
|
||||
</li>
|
||||
);
|
||||
})}
|
||||
</ul>
|
||||
</div>
|
||||
))}
|
||||
{tree.map(renderNode)}
|
||||
</nav>
|
||||
);
|
||||
}
|
||||
@@ -64,14 +176,16 @@ export function DocsNav({
|
||||
export function DocsNavSkeleton() {
|
||||
return (
|
||||
<nav className="portal-docs__nav" aria-hidden>
|
||||
{Array.from({ length: 4 }).map((_, gi) => (
|
||||
{Array.from({ length: 5 }).map((_, gi) => (
|
||||
<div key={gi} className="portal-docs__nav-group">
|
||||
<Skeleton width="7rem" height="0.75rem" />
|
||||
<div className="portal-docs__nav-list">
|
||||
{Array.from({ length: 3 }).map((_, li) => (
|
||||
<Skeleton key={li} width="80%" height="0.875rem" />
|
||||
))}
|
||||
</div>
|
||||
{gi === 0 && (
|
||||
<div className="portal-docs__nav-list">
|
||||
{Array.from({ length: 4 }).map((_, li) => (
|
||||
<Skeleton key={li} width="80%" height="0.875rem" />
|
||||
))}
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
))}
|
||||
</nav>
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
import { useEffect, useRef, useState } from "react";
|
||||
import { useTranslation } from "react-i18next";
|
||||
import { Button } from "@app/ui";
|
||||
import type { SearchResult, Segment } from "@portal/docs/search";
|
||||
|
||||
/** Render highlighted segments, wrapping matched runs in <mark>. */
|
||||
function Highlighted({ segments }: { segments: Segment[] }) {
|
||||
return (
|
||||
<>
|
||||
{segments.map((s, i) =>
|
||||
s.hit ? (
|
||||
<mark key={i} className="portal-docs__hl">
|
||||
{s.text}
|
||||
</mark>
|
||||
) : (
|
||||
<span key={i}>{s.text}</span>
|
||||
),
|
||||
)}
|
||||
</>
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Docs search box + results. While a query is active it shows a ranked list of
|
||||
* matching docs — each with its section, a highlighted title, and a content
|
||||
* snippet — that navigates on click (or Enter). Arrow keys move the selection.
|
||||
*/
|
||||
export function DocsSearch({
|
||||
query,
|
||||
onQueryChange,
|
||||
results,
|
||||
onSelect,
|
||||
}: {
|
||||
query: string;
|
||||
onQueryChange: (q: string) => void;
|
||||
results: SearchResult[];
|
||||
onSelect: (docId: string) => void;
|
||||
}) {
|
||||
const { t } = useTranslation();
|
||||
// -1 = nothing pre-selected; arrow keys drive this, the mouse uses CSS :hover.
|
||||
const [activeIndex, setActiveIndex] = useState(-1);
|
||||
const listRef = useRef<HTMLUListElement>(null);
|
||||
const hasQuery = query.trim().length > 0;
|
||||
|
||||
useEffect(() => setActiveIndex(-1), [query]);
|
||||
|
||||
useEffect(() => {
|
||||
listRef.current
|
||||
?.querySelector<HTMLElement>('[data-active="true"]')
|
||||
?.scrollIntoView?.({ block: "nearest" });
|
||||
}, [activeIndex]);
|
||||
|
||||
const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
|
||||
if (e.key === "Escape") {
|
||||
onQueryChange("");
|
||||
return;
|
||||
}
|
||||
if (!results.length) return;
|
||||
if (e.key === "ArrowDown") {
|
||||
e.preventDefault();
|
||||
setActiveIndex((i) => Math.min(i + 1, results.length - 1));
|
||||
} else if (e.key === "ArrowUp") {
|
||||
e.preventDefault();
|
||||
setActiveIndex((i) => Math.max(i - 1, 0));
|
||||
} else if (e.key === "Enter") {
|
||||
e.preventDefault();
|
||||
const hit = results[activeIndex >= 0 ? activeIndex : 0];
|
||||
if (hit) onSelect(hit.id);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<div className="portal-docs__search">
|
||||
<div className="portal-docs__search-box">
|
||||
<span className="portal-docs__search-icon" aria-hidden>
|
||||
⌕
|
||||
</span>
|
||||
<input
|
||||
type="search"
|
||||
className="portal-docs__search-input"
|
||||
placeholder={t("portal.docs.search.placeholder")}
|
||||
value={query}
|
||||
onChange={(e) => onQueryChange(e.target.value)}
|
||||
onKeyDown={onKeyDown}
|
||||
aria-label={t("portal.docs.search.placeholder")}
|
||||
/>
|
||||
</div>
|
||||
|
||||
{hasQuery && (
|
||||
<div className="portal-docs__results">
|
||||
{results.length === 0 ? (
|
||||
<p className="portal-docs__nav-empty">
|
||||
{t("portal.docs.search.empty")}
|
||||
</p>
|
||||
) : (
|
||||
<>
|
||||
<div className="portal-docs__results-count">
|
||||
{t("portal.docs.search.results", { count: results.length })}
|
||||
</div>
|
||||
<ul ref={listRef} className="portal-docs__results-list">
|
||||
{results.map((r, i) => (
|
||||
<li key={r.id}>
|
||||
<Button
|
||||
variant="tertiary"
|
||||
fullWidth
|
||||
justify="start"
|
||||
className={
|
||||
"portal-docs__result" +
|
||||
(i === activeIndex ? " is-active" : "")
|
||||
}
|
||||
data-active={i === activeIndex}
|
||||
onClick={() => onSelect(r.id)}
|
||||
>
|
||||
<span className="portal-docs__result-body">
|
||||
<span className="portal-docs__result-head">
|
||||
<span className="portal-docs__result-title">
|
||||
<Highlighted segments={r.titleSegments} />
|
||||
</span>
|
||||
<span className="portal-docs__result-section">
|
||||
{r.sectionLabel}
|
||||
</span>
|
||||
</span>
|
||||
<span className="portal-docs__result-snippet">
|
||||
<Highlighted segments={r.snippet} />
|
||||
</span>
|
||||
</span>
|
||||
</Button>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,80 @@
|
||||
import { useEffect, useState, type RefObject } from "react";
|
||||
import { useTranslation } from "react-i18next";
|
||||
import type { Heading } from "@portal/docs/headings";
|
||||
|
||||
/**
|
||||
* "On this page" table of contents. Lists the current doc's H2/H3 headings,
|
||||
* scrolls the reading pane to a heading on click, and highlights the section
|
||||
* currently in view (scroll-spy against the pane's scroll container).
|
||||
*/
|
||||
export function DocsToc({
|
||||
headings,
|
||||
scrollRef,
|
||||
}: {
|
||||
headings: Heading[];
|
||||
scrollRef: RefObject<HTMLElement | null>;
|
||||
}) {
|
||||
const { t } = useTranslation();
|
||||
const [active, setActive] = useState<string>(headings[0]?.slug ?? "");
|
||||
|
||||
useEffect(() => {
|
||||
const root = scrollRef.current;
|
||||
if (!root || headings.length === 0) return;
|
||||
setActive(headings[0].slug);
|
||||
|
||||
const visible = new Set<string>();
|
||||
const observer = new IntersectionObserver(
|
||||
(entries) => {
|
||||
for (const e of entries) {
|
||||
if (e.isIntersecting) visible.add(e.target.id);
|
||||
else visible.delete(e.target.id);
|
||||
}
|
||||
// The topmost heading currently within the active zone wins.
|
||||
const current = headings.find((h) => visible.has(h.slug));
|
||||
if (current) setActive(current.slug);
|
||||
},
|
||||
// Active zone = the top ~30% of the reading pane.
|
||||
{ root, rootMargin: "0px 0px -70% 0px", threshold: 0 },
|
||||
);
|
||||
|
||||
const els = headings
|
||||
.map((h) => root.querySelector(`[id="${h.slug}"]`))
|
||||
.filter((el): el is Element => el !== null);
|
||||
els.forEach((el) => observer.observe(el));
|
||||
return () => observer.disconnect();
|
||||
}, [headings, scrollRef]);
|
||||
|
||||
const onSelect = (slug: string) => {
|
||||
scrollRef.current
|
||||
?.querySelector(`[id="${slug}"]`)
|
||||
?.scrollIntoView({ block: "start", behavior: "smooth" });
|
||||
setActive(slug);
|
||||
};
|
||||
|
||||
return (
|
||||
<nav className="portal-docs__toc" aria-label={t("portal.docs.toc.title")}>
|
||||
<div className="portal-docs__toc-title">{t("portal.docs.toc.title")}</div>
|
||||
<ul className="portal-docs__toc-list">
|
||||
{headings.map((h) => (
|
||||
<li key={h.slug}>
|
||||
<a
|
||||
href={`#${h.slug}`}
|
||||
className={
|
||||
"portal-docs__toc-link" +
|
||||
(h.level === 3 ? " is-sub" : "") +
|
||||
(active === h.slug ? " is-active" : "")
|
||||
}
|
||||
aria-current={active === h.slug ? "location" : undefined}
|
||||
onClick={(e) => {
|
||||
e.preventDefault();
|
||||
onSelect(h.slug);
|
||||
}}
|
||||
>
|
||||
{h.text}
|
||||
</a>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</nav>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,131 @@
|
||||
import { isValidElement, useState, type ReactNode } from "react";
|
||||
import ReactMarkdown, {
|
||||
defaultUrlTransform,
|
||||
type Components,
|
||||
} from "react-markdown";
|
||||
import remarkGfm from "remark-gfm";
|
||||
import { Button } from "@app/ui";
|
||||
import { makeSlugger } from "@portal/docs/headings";
|
||||
|
||||
/** Flatten a heading's React children to plain text for its anchor id. */
|
||||
function childText(node: ReactNode): string {
|
||||
if (typeof node === "string" || typeof node === "number") return String(node);
|
||||
if (Array.isArray(node)) return node.map(childText).join("");
|
||||
if (isValidElement(node)) {
|
||||
return childText((node.props as { children?: ReactNode }).children);
|
||||
}
|
||||
return "";
|
||||
}
|
||||
|
||||
// Keep our internal `doc:` scheme; sanitize every other URL as react-markdown
|
||||
// would by default (it strips unknown protocols, which would kill doc: links).
|
||||
function urlTransform(url: string): string {
|
||||
return url.startsWith("doc:") ? url : defaultUrlTransform(url);
|
||||
}
|
||||
|
||||
/**
|
||||
* Renders a doc's normalised markdown. Internal cross-doc links carry the
|
||||
* `doc:` scheme (see the sync transform) and are intercepted here so they
|
||||
* navigate within the portal instead of leaving the app.
|
||||
*/
|
||||
|
||||
function CopyButton({ text }: { text: string }) {
|
||||
const [copied, setCopied] = useState(false);
|
||||
return (
|
||||
<Button
|
||||
variant="tertiary"
|
||||
size="sm"
|
||||
className="portal-docs__md-copy"
|
||||
onClick={() =>
|
||||
void navigator.clipboard.writeText(text).then(() => {
|
||||
setCopied(true);
|
||||
setTimeout(() => setCopied(false), 1500);
|
||||
})
|
||||
}
|
||||
>
|
||||
{copied ? "✓ Copied" : "Copy"}
|
||||
</Button>
|
||||
);
|
||||
}
|
||||
|
||||
function buildComponents(
|
||||
onNavigate: (docId: string) => void,
|
||||
slug: (text: string) => string,
|
||||
): Components {
|
||||
return {
|
||||
h2: ({ children }) => <h2 id={slug(childText(children))}>{children}</h2>,
|
||||
h3: ({ children }) => <h3 id={slug(childText(children))}>{children}</h3>,
|
||||
a: ({ href, children }) => {
|
||||
if (href?.startsWith("doc:")) {
|
||||
const id = href.slice(4);
|
||||
return (
|
||||
<a
|
||||
href={`#${id}`}
|
||||
onClick={(e) => {
|
||||
e.preventDefault();
|
||||
onNavigate(id);
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</a>
|
||||
);
|
||||
}
|
||||
const external = /^https?:/i.test(href ?? "");
|
||||
return (
|
||||
<a
|
||||
href={href}
|
||||
target={external ? "_blank" : undefined}
|
||||
rel={external ? "noopener noreferrer" : undefined}
|
||||
>
|
||||
{children}
|
||||
</a>
|
||||
);
|
||||
},
|
||||
// Eager, not lazy: lazy-loading inside the docs' own scroll container isn't
|
||||
// reliably triggered, and docs pages have only a handful of images.
|
||||
img: ({ node: _node, ...props }) => (
|
||||
<img {...props} className="portal-docs__md-img" />
|
||||
),
|
||||
pre: ({ children }) => {
|
||||
const code = isValidElement(children)
|
||||
? String(
|
||||
(children.props as { children?: unknown }).children ?? "",
|
||||
).replace(/\n$/, "")
|
||||
: String(children ?? "");
|
||||
return (
|
||||
<div className="portal-docs__md-pre">
|
||||
<pre>{children}</pre>
|
||||
<CopyButton text={code} />
|
||||
</div>
|
||||
);
|
||||
},
|
||||
table: ({ children }) => (
|
||||
<div className="portal-docs__md-tablewrap">
|
||||
<table>{children}</table>
|
||||
</div>
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
export function MarkdownDoc({
|
||||
markdown,
|
||||
onNavigate,
|
||||
}: {
|
||||
markdown: string;
|
||||
onNavigate: (docId: string) => void;
|
||||
}) {
|
||||
// A fresh de-duping slugger per render; react-markdown invokes h2/h3 in
|
||||
// document order, so ids line up with the TOC's extractHeadings slugs.
|
||||
const slug = makeSlugger();
|
||||
return (
|
||||
<div className="portal-docs__md">
|
||||
<ReactMarkdown
|
||||
remarkPlugins={[remarkGfm]}
|
||||
urlTransform={urlTransform}
|
||||
components={buildComponents(onNavigate, slug)}
|
||||
>
|
||||
{markdown}
|
||||
</ReactMarkdown>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -19,10 +19,6 @@ export interface NavEntry {
|
||||
externalUrl?: string;
|
||||
}
|
||||
|
||||
// Developer docs has no built-in portal page yet, so the tab opens the hosted docs
|
||||
// site in a new tab rather than routing to an empty page.
|
||||
const DEVELOPER_DOCS_URL = "https://docs.stirlingpdf.com/";
|
||||
|
||||
// Sidebar nav groups. This is a flavor seam: the SaaS build shadows this file to
|
||||
// drop sections not yet shipped there (see src/portal-saas/components/sidebarGroups).
|
||||
export const GROUP_PRIMARY: NavEntry[] = [{ id: "home", icon: <HomeIcon /> }];
|
||||
@@ -38,5 +34,5 @@ export const GROUP_OPERATIONAL: NavEntry[] = [
|
||||
export const GROUP_PLATFORM: NavEntry[] = [
|
||||
{ id: "infrastructure", icon: <InfrastructureIcon /> },
|
||||
{ id: "usage", icon: <UsageIcon /> },
|
||||
{ id: "docs", icon: <DocsIcon />, externalUrl: DEVELOPER_DOCS_URL },
|
||||
{ id: "docs", icon: <DocsIcon /> },
|
||||
];
|
||||
|
||||
@@ -28,7 +28,7 @@ export const VIEW_LABELS: Record<ViewId, string> = {
|
||||
documents: "Documents",
|
||||
infrastructure: "Infrastructure",
|
||||
usage: "Usage & Billing",
|
||||
docs: "Developer Docs",
|
||||
docs: "Documentation",
|
||||
procurement: "Procurement",
|
||||
settings: "Settings",
|
||||
};
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { extractHeadings, slugify } from "@portal/docs/headings";
|
||||
|
||||
describe("slugify", () => {
|
||||
it("lowercases, hyphenates, and trims punctuation", () => {
|
||||
expect(slugify("How it Works!")).toBe("how-it-works");
|
||||
expect(slugify(" Trailing & spaces ")).toBe("trailing-spaces");
|
||||
});
|
||||
});
|
||||
|
||||
describe("extractHeadings", () => {
|
||||
it("extracts H2/H3 only, with slugs matching the rendered ids", () => {
|
||||
const md = [
|
||||
"# Page Title",
|
||||
"## How it Works",
|
||||
"text",
|
||||
"### Sub Section",
|
||||
"#### Too Deep",
|
||||
"## Operations",
|
||||
].join("\n");
|
||||
expect(extractHeadings(md)).toEqual([
|
||||
{ level: 2, text: "How it Works", slug: "how-it-works" },
|
||||
{ level: 3, text: "Sub Section", slug: "sub-section" },
|
||||
{ level: 2, text: "Operations", slug: "operations" },
|
||||
]);
|
||||
});
|
||||
|
||||
it("de-duplicates repeated heading text into unique slugs", () => {
|
||||
const md = ["## What Changed", "### What Changed", "## What Changed"].join(
|
||||
"\n",
|
||||
);
|
||||
expect(extractHeadings(md).map((h) => h.slug)).toEqual([
|
||||
"what-changed",
|
||||
"what-changed-1",
|
||||
"what-changed-2",
|
||||
]);
|
||||
});
|
||||
|
||||
it("ignores headings inside fenced code and strips inline marks", () => {
|
||||
const md = ["```", "## not a heading", "```", "## `Code` and *em*"].join(
|
||||
"\n",
|
||||
);
|
||||
expect(extractHeadings(md)).toEqual([
|
||||
{ level: 2, text: "Code and em", slug: "code-and-em" },
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,48 @@
|
||||
/**
|
||||
* Heading extraction for the "On this page" table of contents. The same
|
||||
* `slugify` is used here and in MarkdownDoc's heading renderer, so the TOC links
|
||||
* and the rendered heading ids always match.
|
||||
*/
|
||||
|
||||
export interface Heading {
|
||||
/** 2 or 3 (H2/H3). */
|
||||
level: number;
|
||||
text: string;
|
||||
slug: string;
|
||||
}
|
||||
|
||||
/** "How it Works!" → "how-it-works" (the base id, before de-duplication). */
|
||||
export function slugify(text: string): string {
|
||||
return text
|
||||
.toLowerCase()
|
||||
.trim()
|
||||
.replace(/[^a-z0-9]+/g, "-")
|
||||
.replace(/^-+|-+$/g, "");
|
||||
}
|
||||
|
||||
/**
|
||||
* A stateful slugger that de-duplicates: repeated heading text gets `-1`, `-2`, …
|
||||
* The TOC extraction and MarkdownDoc's heading renderer each make one and feed it
|
||||
* headings in document order, so their slugs (and thus link ↔ id) always match.
|
||||
*/
|
||||
export function makeSlugger(): (text: string) => string {
|
||||
const seen = new Map<string, number>();
|
||||
return (text: string) => {
|
||||
const base = slugify(text) || "section";
|
||||
const n = seen.get(base) ?? 0;
|
||||
seen.set(base, n + 1);
|
||||
return n === 0 ? base : `${base}-${n}`;
|
||||
};
|
||||
}
|
||||
|
||||
/** Extract H2/H3 headings from a doc body, skipping fenced code blocks. */
|
||||
export function extractHeadings(markdown: string): Heading[] {
|
||||
const noCode = markdown.replace(/^(```|~~~)[\s\S]*?^\1[ \t]*$/gm, "");
|
||||
const slug = makeSlugger();
|
||||
const headings: Heading[] = [];
|
||||
for (const m of noCode.matchAll(/^ {0,3}(#{2,3})[ \t]+(.+?)[ \t]*#*$/gm)) {
|
||||
const text = m[2].replace(/[`*_]/g, "").trim();
|
||||
if (text) headings.push({ level: m[1].length, text, slug: slug(text) });
|
||||
}
|
||||
return headings;
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
/**
|
||||
* Runtime accessors over the generated docs manifest. This is the only module
|
||||
* that imports the (large) JSON, so lazy-loading the docs view keeps it in its
|
||||
* own chunk. Regenerate the JSON with `npm run docs:sync`.
|
||||
*/
|
||||
// Imported as a raw string (not a JSON module) so tsc doesn't infer a ~half-MB
|
||||
// literal type; parsed once here into the typed manifest.
|
||||
import manifestRaw from "@portal/generated/docsManifest.json?raw";
|
||||
import type {
|
||||
DocEntry,
|
||||
DocsManifest,
|
||||
DocsNavSection,
|
||||
} from "@portal/docs/manifest/transform";
|
||||
|
||||
const manifest = JSON.parse(manifestRaw) as DocsManifest;
|
||||
|
||||
/** Provenance of the current manifest (repo + ref it was generated from). */
|
||||
export const docsSource = manifest.source;
|
||||
|
||||
/** The auto-sorted nav tree (sections → items). */
|
||||
export function loadDocsNav(): DocsNavSection[] {
|
||||
return manifest.nav;
|
||||
}
|
||||
|
||||
/** A single doc by id, or undefined if it isn't in the manifest. */
|
||||
export function loadDoc(id: string): DocEntry | undefined {
|
||||
return manifest.docs[id];
|
||||
}
|
||||
|
||||
/** Every doc, for building the search index. */
|
||||
export function allDocs(): DocEntry[] {
|
||||
return Object.values(manifest.docs);
|
||||
}
|
||||
|
||||
/** The first doc id (first item of the first section) — the default landing. */
|
||||
export function firstDocId(): string | undefined {
|
||||
return manifest.nav[0]?.items[0]?.id;
|
||||
}
|
||||
@@ -0,0 +1,208 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
buildManifest,
|
||||
convertAdmonitions,
|
||||
demoteHeadings,
|
||||
docIdForPath,
|
||||
humanize,
|
||||
parseFrontmatter,
|
||||
resolveRelative,
|
||||
rewriteReferences,
|
||||
sectionIcon,
|
||||
stripJsxTags,
|
||||
stripMdxImports,
|
||||
stripRedundantH1,
|
||||
type CategoryMap,
|
||||
type RawDoc,
|
||||
} from "@portal/docs/manifest/transform";
|
||||
|
||||
const OPTS = {
|
||||
repo: "Owner/Repo",
|
||||
ref: "main",
|
||||
root: "docs",
|
||||
siteBaseUrl: "https://docs.example.com",
|
||||
};
|
||||
|
||||
describe("parseFrontmatter", () => {
|
||||
it("splits scalar YAML frontmatter from the body", () => {
|
||||
const { data, body } = parseFrontmatter(
|
||||
"---\ntitle: OCR\nsidebar_position: 7\n---\n# Heading\ntext",
|
||||
);
|
||||
expect(data.title).toBe("OCR");
|
||||
expect(data.sidebar_position).toBe(7);
|
||||
expect(body).toBe("# Heading\ntext");
|
||||
});
|
||||
|
||||
it("returns the whole content as body when there is no frontmatter", () => {
|
||||
const { data, body } = parseFrontmatter("# Just a doc\nbody");
|
||||
expect(data).toEqual({});
|
||||
expect(body).toBe("# Just a doc\nbody");
|
||||
});
|
||||
|
||||
it("normalises CRLF line endings", () => {
|
||||
const { data } = parseFrontmatter("---\r\nid: x\r\n---\r\nbody");
|
||||
expect(data.id).toBe("x");
|
||||
});
|
||||
});
|
||||
|
||||
describe("id + label helpers", () => {
|
||||
it("slugifies nested paths", () => {
|
||||
expect(docIdForPath("Configuration/OCR.md")).toBe("configuration/ocr");
|
||||
expect(docIdForPath("Getting Started.md")).toBe("getting-started");
|
||||
});
|
||||
|
||||
it("humanises file/dir names", () => {
|
||||
expect(humanize("Getting-Started.md")).toBe("Getting Started");
|
||||
});
|
||||
|
||||
it("picks a section icon from the label", () => {
|
||||
expect(sectionIcon("Configuration")).toBe("⚙");
|
||||
expect(sectionIcon("Totally Unknown")).toBe("◇");
|
||||
});
|
||||
});
|
||||
|
||||
describe("MDX normalisation", () => {
|
||||
it("converts admonitions to titled blockquotes", () => {
|
||||
const out = convertAdmonitions(":::tip Upgrading?\nread this\n:::");
|
||||
expect(out).toContain("> **💡 Tip: Upgrading?**");
|
||||
expect(out).toContain("> read this");
|
||||
});
|
||||
|
||||
it("strips import/export statements", () => {
|
||||
const out = stripMdxImports("import Tabs from '@theme/Tabs';\n# Keep");
|
||||
expect(out).toBe("# Keep");
|
||||
});
|
||||
|
||||
it("removes JSX component tags but keeps inner content", () => {
|
||||
expect(
|
||||
stripJsxTags("<Tabs>\n<TabItem value='a'>keep</TabItem>\n</Tabs>"),
|
||||
).toContain("keep");
|
||||
expect(stripJsxTags("<TabItem>x</TabItem>")).not.toMatch(/<TabItem/);
|
||||
});
|
||||
|
||||
it("demotes body H1 to H2 but leaves code comments alone", () => {
|
||||
const md = "# Title\n\n```bash\n# a shell comment\n```";
|
||||
const out = demoteHeadings(md);
|
||||
expect(out).toContain("## Title");
|
||||
expect(out).toContain("# a shell comment");
|
||||
});
|
||||
|
||||
it("strips a leading H1 that duplicates the page title", () => {
|
||||
expect(stripRedundantH1("# OCR\nbody", "OCR")).toBe("body");
|
||||
expect(stripRedundantH1("# Other\nbody", "OCR")).toBe("# Other\nbody");
|
||||
});
|
||||
});
|
||||
|
||||
describe("resolveRelative", () => {
|
||||
it("collapses ./ and ../ against a base dir", () => {
|
||||
expect(resolveRelative("Configuration", "./OCR.md")).toBe(
|
||||
"Configuration/OCR.md",
|
||||
);
|
||||
expect(
|
||||
resolveRelative("Configuration", "../Functionality/Compare.md"),
|
||||
).toBe("Functionality/Compare.md");
|
||||
});
|
||||
});
|
||||
|
||||
describe("rewriteReferences", () => {
|
||||
const ctx = {
|
||||
dir: "Configuration",
|
||||
// Keys are lowercased file paths (spaces preserved), as buildManifest builds them.
|
||||
pathToId: new Map([
|
||||
[
|
||||
"configuration/system and security",
|
||||
"configuration/system-and-security",
|
||||
],
|
||||
]),
|
||||
rawBase: "https://raw.example.com/Owner/Repo/main",
|
||||
siteBaseUrl: "https://docs.example.com",
|
||||
};
|
||||
|
||||
it("rewrites resolvable internal links to the doc: scheme (decoded + case-insensitive)", () => {
|
||||
const out = rewriteReferences(
|
||||
"see [sec](./System%20and%20Security.md)",
|
||||
ctx,
|
||||
"docs",
|
||||
);
|
||||
expect(out).toBe("see [sec](doc:configuration/system-and-security)");
|
||||
});
|
||||
|
||||
it("falls back to the live docs site for unresolved internal links", () => {
|
||||
const out = rewriteReferences("[x](./Missing.md)", ctx, "docs");
|
||||
expect(out).toBe("[x](https://docs.example.com/Configuration/Missing)");
|
||||
});
|
||||
|
||||
it("leaves absolute and anchor links untouched", () => {
|
||||
const md = "[a](https://x.com) and [b](#top)";
|
||||
expect(rewriteReferences(md, ctx, "docs")).toBe(md);
|
||||
});
|
||||
|
||||
it("rewrites relative images to absolute raw URLs", () => {
|
||||
expect(rewriteReferences("", ctx, "docs")).toBe(
|
||||
"",
|
||||
);
|
||||
expect(rewriteReferences("", ctx, "docs")).toBe(
|
||||
"",
|
||||
);
|
||||
});
|
||||
|
||||
it("does not rewrite inside fenced code blocks", () => {
|
||||
const md = "```\n[x](./y.md)\n```";
|
||||
expect(rewriteReferences(md, ctx, "docs")).toBe(md);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildManifest", () => {
|
||||
const rawDocs: RawDoc[] = [
|
||||
{
|
||||
relPath: "Getting Started.md",
|
||||
content: "---\nsidebar_position: 0\n---\nintro",
|
||||
},
|
||||
{
|
||||
relPath: "Configuration/OCR.md",
|
||||
content: "---\ntitle: OCR\nsidebar_position: 7\n---\n# OCR\nbody",
|
||||
},
|
||||
{
|
||||
relPath: "Configuration/DATABASE.md",
|
||||
content: "---\nsidebar_position: 1\n---\n# Database\nsee [ocr](./OCR.md)",
|
||||
},
|
||||
];
|
||||
const categories: CategoryMap = {
|
||||
Configuration: { label: "Configuration", position: 5 },
|
||||
};
|
||||
|
||||
it("auto-sorts sections (root Overview first, then by category position)", () => {
|
||||
const m = buildManifest(rawDocs, categories, OPTS);
|
||||
expect(m.nav.map((s) => s.id)).toEqual(["overview", "configuration"]);
|
||||
expect(m.nav[0].label).toBe("Overview");
|
||||
expect(m.nav[1].label).toBe("Configuration");
|
||||
});
|
||||
|
||||
it("orders nav items by sidebar_position", () => {
|
||||
const m = buildManifest(rawDocs, categories, OPTS);
|
||||
const config = m.nav.find((s) => s.id === "configuration")!;
|
||||
expect(config.items.map((i) => i.id)).toEqual([
|
||||
"configuration/database",
|
||||
"configuration/ocr",
|
||||
]);
|
||||
});
|
||||
|
||||
it("derives titles from frontmatter, heading, then filename", () => {
|
||||
const m = buildManifest(rawDocs, categories, OPTS);
|
||||
expect(m.docs["configuration/ocr"].title).toBe("OCR");
|
||||
expect(m.docs["getting-started"].title).toBe("Getting Started");
|
||||
});
|
||||
|
||||
it("resolves cross-doc links and records source/edit urls", () => {
|
||||
const m = buildManifest(rawDocs, categories, OPTS);
|
||||
expect(m.docs["configuration/database"].markdown).toContain(
|
||||
"[ocr](doc:configuration/ocr)",
|
||||
);
|
||||
expect(m.docs["configuration/ocr"].sourcePath).toBe(
|
||||
"docs/Configuration/OCR.md",
|
||||
);
|
||||
expect(m.docs["configuration/ocr"].editUrl).toBe(
|
||||
"https://github.com/Owner/Repo/blob/main/docs/Configuration/OCR.md",
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,481 @@
|
||||
/**
|
||||
* Pure transforms that turn the Docusaurus docs repo into the portal docs
|
||||
* manifest. No I/O and no external deps so `tsx` (the sync CLI) and vitest can
|
||||
* both use it. The sync CLI does the fetching; this module does the shaping.
|
||||
*
|
||||
* The auto-sort rules:
|
||||
* - every directory that directly holds markdown becomes a nav section,
|
||||
* labelled + ordered by its `_category_.json` (root files → "Overview"),
|
||||
* - each `.md`/`.mdx` file becomes a nav item, ordered by frontmatter
|
||||
* `sidebar_position` then title,
|
||||
* - Docusaurus MDX is normalised to plain GitHub-flavoured markdown that
|
||||
* react-markdown can render (admonitions, JSX, relative links, images).
|
||||
*/
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
/* Manifest shape (mirrored structurally by @portal/api/docs) */
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
|
||||
export interface DocsNavItem {
|
||||
id: string;
|
||||
label: string;
|
||||
badge?: string;
|
||||
}
|
||||
|
||||
export interface DocsNavSection {
|
||||
id: string;
|
||||
label: string;
|
||||
icon: string;
|
||||
items: DocsNavItem[];
|
||||
}
|
||||
|
||||
export interface DocEntry {
|
||||
id: string;
|
||||
title: string;
|
||||
description?: string;
|
||||
section: string;
|
||||
markdown: string;
|
||||
sourcePath: string;
|
||||
editUrl: string;
|
||||
}
|
||||
|
||||
export interface DocsManifest {
|
||||
source: { repo: string; ref: string; root: string };
|
||||
nav: DocsNavSection[];
|
||||
docs: Record<string, DocEntry>;
|
||||
}
|
||||
|
||||
/** One markdown file read from the repo, before shaping. */
|
||||
export interface RawDoc {
|
||||
/** Posix path relative to the docs root, e.g. "Configuration/OCR.md". */
|
||||
relPath: string;
|
||||
content: string;
|
||||
}
|
||||
|
||||
/** `_category_.json` contents, keyed by posix dir path relative to docs root. */
|
||||
export type CategoryMap = Record<string, { label?: string; position?: number }>;
|
||||
|
||||
export interface BuildOptions {
|
||||
repo: string;
|
||||
ref: string;
|
||||
/** Docs root within the repo, e.g. "docs". */
|
||||
root: string;
|
||||
/** Live docs site base, used as the fallback for unresolved internal links. */
|
||||
siteBaseUrl: string;
|
||||
}
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
/* Small helpers */
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
|
||||
const SECTION_ICONS: Array<[RegExp, string]> = [
|
||||
[/overview|getting started|start/i, "▶"],
|
||||
[/config/i, "⚙"],
|
||||
[/function|tool|feature/i, "▤"],
|
||||
[/install|deploy/i, "⤓"],
|
||||
[/migrat|upgrade/i, "⇄"],
|
||||
[/security|sign|auth/i, "🛡"],
|
||||
[/convert/i, "⇋"],
|
||||
[/page/i, "▦"],
|
||||
[/api|develop/i, "{ }"],
|
||||
];
|
||||
|
||||
/** A single-glyph icon for a section, chosen from its label. */
|
||||
export function sectionIcon(label: string): string {
|
||||
for (const [re, glyph] of SECTION_ICONS) if (re.test(label)) return glyph;
|
||||
return "◇";
|
||||
}
|
||||
|
||||
/** "Getting-Started_Guide" → "Getting Started Guide". */
|
||||
export function humanize(name: string): string {
|
||||
return name
|
||||
.replace(/\.mdx?$/i, "")
|
||||
.replace(/[-_]+/g, " ")
|
||||
.replace(/\s+/g, " ")
|
||||
.trim()
|
||||
.replace(/\b\w/g, (c) => c.toUpperCase());
|
||||
}
|
||||
|
||||
/** Lowercase, hyphenated, url-safe id for a path segment. */
|
||||
export function slugifySegment(name: string): string {
|
||||
return name
|
||||
.replace(/\.mdx?$/i, "")
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9]+/g, "-")
|
||||
.replace(/^-+|-+$/g, "");
|
||||
}
|
||||
|
||||
/** Docs-root-relative posix path → stable doc id, e.g. "configuration/ocr". */
|
||||
export function docIdForPath(relPath: string): string {
|
||||
return relPath.split("/").map(slugifySegment).filter(Boolean).join("/");
|
||||
}
|
||||
|
||||
/** Posix dirname ("" for a root-level file). */
|
||||
export function dirOf(relPath: string): string {
|
||||
const i = relPath.lastIndexOf("/");
|
||||
return i === -1 ? "" : relPath.slice(0, i);
|
||||
}
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
/* Frontmatter */
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
|
||||
export interface Frontmatter {
|
||||
data: Record<string, string | number>;
|
||||
body: string;
|
||||
}
|
||||
|
||||
/** Split leading `--- ... ---` YAML frontmatter (scalar keys only) from body. */
|
||||
export function parseFrontmatter(content: string): Frontmatter {
|
||||
const normalised = content.replace(/\r\n/g, "\n");
|
||||
if (!normalised.startsWith("---\n")) return { data: {}, body: normalised };
|
||||
const end = normalised.indexOf("\n---", 4);
|
||||
if (end === -1) return { data: {}, body: normalised };
|
||||
const raw = normalised.slice(4, end);
|
||||
const rest = normalised.slice(end + 4).replace(/^\n/, "");
|
||||
const data: Record<string, string | number> = {};
|
||||
for (const line of raw.split("\n")) {
|
||||
const m = /^([A-Za-z0-9_]+):\s*(.*)$/.exec(line);
|
||||
if (!m) continue;
|
||||
let value: string | number = m[2].trim().replace(/^["']|["']$/g, "");
|
||||
if (/^-?\d+(\.\d+)?$/.test(value)) value = Number(value);
|
||||
data[m[1]] = value;
|
||||
}
|
||||
return { data, body: rest };
|
||||
}
|
||||
|
||||
/** First `# H1` heading text in a body, if any. */
|
||||
export function firstHeading(body: string): string | undefined {
|
||||
const m = /^#\s+(.+?)\s*$/m.exec(stripCodeFences(body));
|
||||
return m ? m[1].trim() : undefined;
|
||||
}
|
||||
|
||||
/** Blank out fenced code blocks so heading/link scans ignore their contents. */
|
||||
function stripCodeFences(md: string): string {
|
||||
return md.replace(/^(```|~~~)[\s\S]*?^\1\s*$/gm, "");
|
||||
}
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
/* Body normalisation (MDX → plain markdown) */
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
|
||||
/** Run `fn` over the non-fenced-code spans of `md`, leaving code blocks intact. */
|
||||
function mapOutsideCode(md: string, fn: (text: string) => string): string {
|
||||
const parts = md.split(/(^(?:```|~~~)[\s\S]*?^(?:```|~~~)\s*$)/gm);
|
||||
return parts.map((part, i) => (i % 2 === 0 ? fn(part) : part)).join("");
|
||||
}
|
||||
|
||||
const ADMONITION_META: Record<string, { icon: string; label: string }> = {
|
||||
tip: { icon: "💡", label: "Tip" },
|
||||
note: { icon: "📝", label: "Note" },
|
||||
info: { icon: "ℹ️", label: "Info" },
|
||||
warning: { icon: "⚠️", label: "Warning" },
|
||||
caution: { icon: "⚠️", label: "Caution" },
|
||||
danger: { icon: "🚫", label: "Danger" },
|
||||
};
|
||||
|
||||
/** `:::tip Title\n…\n:::` → a blockquote with a bold titled first line. */
|
||||
export function convertAdmonitions(md: string): string {
|
||||
const re = /^:::(\w+)[ \t]*(.*)\n([\s\S]*?)^:::[ \t]*$/gm;
|
||||
return md.replace(re, (_all, type: string, title: string, body: string) => {
|
||||
const meta = ADMONITION_META[type.toLowerCase()] ?? {
|
||||
icon: "•",
|
||||
label: humanize(type),
|
||||
};
|
||||
const heading = title.trim()
|
||||
? `${meta.label}: ${title.trim()}`
|
||||
: meta.label;
|
||||
const quoted = body
|
||||
.replace(/\s+$/, "")
|
||||
.split("\n")
|
||||
.map((l) => (l ? `> ${l}` : ">"))
|
||||
.join("\n");
|
||||
return `> **${meta.icon} ${heading}**\n>\n${quoted}\n`;
|
||||
});
|
||||
}
|
||||
|
||||
/** Drop MDX `import`/`export` statement lines (outside code). */
|
||||
export function stripMdxImports(md: string): string {
|
||||
return md
|
||||
.split("\n")
|
||||
.filter((l) => !/^\s*(import|export)\s.+from\s.+;?\s*$/.test(l))
|
||||
.filter((l) => !/^\s*import\s+['"][^'"]+['"];?\s*$/.test(l))
|
||||
.join("\n");
|
||||
}
|
||||
|
||||
/** Remove JSX component tags (Capitalised), keeping any inner content. */
|
||||
export function stripJsxTags(md: string): string {
|
||||
return md.replace(/<\/?[A-Z][A-Za-z0-9.]*(?:\s[^>]*?)?\/?>/g, "");
|
||||
}
|
||||
|
||||
/** Resolve a relative posix path against a base dir, collapsing `.`/`..`. */
|
||||
export function resolveRelative(baseDir: string, target: string): string {
|
||||
const stack = baseDir ? baseDir.split("/") : [];
|
||||
for (const seg of target.split("/")) {
|
||||
if (seg === "" || seg === ".") continue;
|
||||
if (seg === "..") stack.pop();
|
||||
else stack.push(seg);
|
||||
}
|
||||
return stack.join("/");
|
||||
}
|
||||
|
||||
interface LinkContext {
|
||||
dir: string;
|
||||
pathToId: Map<string, string>;
|
||||
rawBase: string;
|
||||
siteBaseUrl: string;
|
||||
}
|
||||
|
||||
/** Split "path#anchor" → [path, "#anchor" | ""]. */
|
||||
function splitAnchor(target: string): [string, string] {
|
||||
const i = target.indexOf("#");
|
||||
return i === -1 ? [target, ""] : [target.slice(0, i), target.slice(i)];
|
||||
}
|
||||
|
||||
/** Percent-decode a link path, tolerating malformed escapes. */
|
||||
function decodePath(p: string): string {
|
||||
try {
|
||||
return decodeURIComponent(p);
|
||||
} catch {
|
||||
return p;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Look up the doc id for a relative link target. Keys in pathToId are lowercased
|
||||
* so links work whether they use the filename or a slug, in any case, and with
|
||||
* percent-encoded spaces (the repo links to "System%20and%20Security").
|
||||
*/
|
||||
function resolveDocId(ctx: LinkContext, rawPath: string): string | undefined {
|
||||
const resolved = resolveRelative(ctx.dir, decodePath(rawPath)).toLowerCase();
|
||||
const noExt = resolved.replace(/\.mdx?$/i, "");
|
||||
const candidates = [
|
||||
resolved,
|
||||
noExt,
|
||||
`${noExt.replace(/\/$/, "")}/index`,
|
||||
noExt.replace(/\/index$/i, ""),
|
||||
];
|
||||
for (const c of candidates) {
|
||||
const id = ctx.pathToId.get(c);
|
||||
if (id) return id;
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/** Rewrite a single markdown link target to a portal-usable href. */
|
||||
function rewriteLinkTarget(ctx: LinkContext, target: string): string {
|
||||
const trimmed = target.trim();
|
||||
if (/^(https?:|mailto:|tel:|#|doc:)/i.test(trimmed)) return trimmed;
|
||||
const [path, anchor] = splitAnchor(trimmed);
|
||||
if (!path) return trimmed;
|
||||
const id = resolveDocId(ctx, path);
|
||||
if (id) return `doc:${id}`;
|
||||
// Unresolved internal link → fall back to the live docs site (encode spaces).
|
||||
const slug = resolveRelative(ctx.dir, decodePath(path)).replace(
|
||||
/\.mdx?$/i,
|
||||
"",
|
||||
);
|
||||
const encoded = slug.split("/").map(encodeURIComponent).join("/");
|
||||
return `${ctx.siteBaseUrl}/${encoded}${anchor}`;
|
||||
}
|
||||
|
||||
/** Rewrite a relative image src to an absolute raw-content URL. */
|
||||
function rewriteImageSrc(ctx: LinkContext, src: string, root: string): string {
|
||||
const trimmed = src.trim();
|
||||
if (/^(https?:|data:)/i.test(trimmed)) return trimmed;
|
||||
if (trimmed.startsWith("/")) return `${ctx.rawBase}/static${trimmed}`;
|
||||
const resolved = resolveRelative(`${root}/${ctx.dir}`, trimmed);
|
||||
return `${ctx.rawBase}/${resolved}`;
|
||||
}
|
||||
|
||||
/** Rewrite markdown links + images (outside code) to portal/absolute targets. */
|
||||
export function rewriteReferences(
|
||||
md: string,
|
||||
ctx: LinkContext,
|
||||
root: string,
|
||||
): string {
|
||||
return mapOutsideCode(md, (text) => {
|
||||
// Images first so their `!` prefix isn't eaten by the link pattern.
|
||||
let out = text.replace(
|
||||
/!\[([^\]]*)\]\(([^)\s]+)([^)]*)\)/g,
|
||||
(_m, alt: string, src: string, tail: string) =>
|
||||
`}${tail})`,
|
||||
);
|
||||
out = out.replace(
|
||||
/(^|[^!])\[([^\]]+)\]\(([^)\s]+)([^)]*)\)/g,
|
||||
(_m, pre: string, label: string, href: string, tail: string) =>
|
||||
`${pre}[${label}](${rewriteLinkTarget(ctx, href)}${tail})`,
|
||||
);
|
||||
return out;
|
||||
});
|
||||
}
|
||||
|
||||
/** Drop a leading `# H1` whose text equals the page title (avoids a dup head). */
|
||||
export function stripRedundantH1(md: string, title: string): string {
|
||||
const m = /^\s*#\s+(.+?)\s*(\n|$)/.exec(md);
|
||||
if (m && m[1].trim().toLowerCase() === title.trim().toLowerCase()) {
|
||||
return md.slice(m[0].length).replace(/^\n+/, "");
|
||||
}
|
||||
return md;
|
||||
}
|
||||
|
||||
/** Demote body `# H1` headings to `## H2` so the page title is the sole H1. */
|
||||
export function demoteHeadings(md: string): string {
|
||||
return mapOutsideCode(md, (text) => text.replace(/^# (?=\S)/gm, "## "));
|
||||
}
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
/* Section ordering */
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
|
||||
const ROOT_SECTION_ID = "overview";
|
||||
|
||||
/** Composite order key: `_category_.json.position` down the dir path. */
|
||||
function sectionOrderKey(dir: string, categories: CategoryMap): number[] {
|
||||
if (dir === "") return [-1];
|
||||
const key: number[] = [];
|
||||
const segs = dir.split("/");
|
||||
for (let i = 0; i < segs.length; i++) {
|
||||
const sub = segs.slice(0, i + 1).join("/");
|
||||
key.push(categories[sub]?.position ?? 999);
|
||||
}
|
||||
return key;
|
||||
}
|
||||
|
||||
function compareKeys(a: number[], b: number[]): number {
|
||||
const n = Math.max(a.length, b.length);
|
||||
for (let i = 0; i < n; i++) {
|
||||
const d = (a[i] ?? 0) - (b[i] ?? 0);
|
||||
if (d !== 0) return d;
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
/* Build */
|
||||
/* ──────────────────────────────────────────────────────────────────────── */
|
||||
|
||||
interface ShapedDoc extends DocEntry {
|
||||
navLabel: string;
|
||||
sidebarPosition: number;
|
||||
orderKey: number[];
|
||||
sectionLabel: string;
|
||||
}
|
||||
|
||||
/** Turn raw docs + category metadata into the full portal docs manifest. */
|
||||
export function buildManifest(
|
||||
rawDocs: RawDoc[],
|
||||
categories: CategoryMap,
|
||||
opts: BuildOptions,
|
||||
): DocsManifest {
|
||||
const rawBase = `https://raw.githubusercontent.com/${opts.repo}/${opts.ref}`;
|
||||
const editBase = `https://github.com/${opts.repo}/blob/${opts.ref}`;
|
||||
|
||||
// First pass: assign stable ids so links between docs can resolve. Keys are
|
||||
// lowercased (case-insensitive link matching); both with and without ext.
|
||||
const pathToId = new Map<string, string>();
|
||||
for (const doc of rawDocs) {
|
||||
const id = docIdForPath(doc.relPath);
|
||||
const lower = doc.relPath.toLowerCase();
|
||||
pathToId.set(lower, id);
|
||||
pathToId.set(lower.replace(/\.mdx?$/i, ""), id);
|
||||
}
|
||||
|
||||
const shaped: ShapedDoc[] = rawDocs.map((doc) => {
|
||||
const dir = dirOf(doc.relPath);
|
||||
const { data, body } = parseFrontmatter(doc.content);
|
||||
const title =
|
||||
(typeof data.title === "string" && data.title) ||
|
||||
firstHeading(body) ||
|
||||
humanize(doc.relPath.split("/").pop() ?? doc.relPath);
|
||||
const navLabel =
|
||||
(typeof data.sidebar_label === "string" && data.sidebar_label) || title;
|
||||
const description =
|
||||
typeof data.description === "string" ? data.description : undefined;
|
||||
|
||||
const ctx: LinkContext = {
|
||||
dir,
|
||||
pathToId,
|
||||
rawBase,
|
||||
siteBaseUrl: opts.siteBaseUrl.replace(/\/$/, ""),
|
||||
};
|
||||
let markdown = body;
|
||||
markdown = stripMdxImports(markdown);
|
||||
markdown = convertAdmonitions(markdown);
|
||||
markdown = stripJsxTags(markdown);
|
||||
markdown = rewriteReferences(markdown, ctx, opts.root);
|
||||
markdown = stripRedundantH1(markdown, title);
|
||||
markdown = demoteHeadings(markdown).trim();
|
||||
|
||||
const sectionId = dir === "" ? ROOT_SECTION_ID : docIdForPath(dir);
|
||||
const sectionLabel =
|
||||
dir === ""
|
||||
? "Overview"
|
||||
: (categories[dir]?.label ?? humanize(dir.split("/").pop() ?? dir));
|
||||
|
||||
return {
|
||||
id: docIdForPath(doc.relPath),
|
||||
title,
|
||||
navLabel,
|
||||
description,
|
||||
section: sectionId,
|
||||
markdown,
|
||||
sourcePath: `${opts.root}/${doc.relPath}`,
|
||||
editUrl: `${editBase}/${opts.root}/${doc.relPath}`,
|
||||
sidebarPosition:
|
||||
typeof data.sidebar_position === "number" ? data.sidebar_position : 999,
|
||||
orderKey: sectionOrderKey(dir, categories),
|
||||
sectionLabel,
|
||||
};
|
||||
});
|
||||
|
||||
// Group into sections and order everything deterministically.
|
||||
const bySection = new Map<string, ShapedDoc[]>();
|
||||
for (const doc of shaped) {
|
||||
const list = bySection.get(doc.section) ?? [];
|
||||
list.push(doc);
|
||||
bySection.set(doc.section, list);
|
||||
}
|
||||
|
||||
const nav: DocsNavSection[] = [...bySection.entries()]
|
||||
.map(([id, docs]) => {
|
||||
const first = docs[0];
|
||||
const items = [...docs]
|
||||
.sort(
|
||||
(a, b) =>
|
||||
a.sidebarPosition - b.sidebarPosition ||
|
||||
a.navLabel.localeCompare(b.navLabel),
|
||||
)
|
||||
.map<DocsNavItem>((d) => ({ id: d.id, label: d.navLabel }));
|
||||
return {
|
||||
id,
|
||||
label: first.sectionLabel,
|
||||
icon: sectionIcon(first.sectionLabel),
|
||||
items,
|
||||
_key: first.orderKey,
|
||||
};
|
||||
})
|
||||
.sort(
|
||||
(a, b) => compareKeys(a._key, b._key) || a.label.localeCompare(b.label),
|
||||
)
|
||||
.map(({ _key, ...section }) => section);
|
||||
|
||||
const docs: Record<string, DocEntry> = {};
|
||||
for (const d of shaped) {
|
||||
docs[d.id] = {
|
||||
id: d.id,
|
||||
title: d.title,
|
||||
description: d.description,
|
||||
section: d.section,
|
||||
markdown: d.markdown,
|
||||
sourcePath: d.sourcePath,
|
||||
editUrl: d.editUrl,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
source: { repo: opts.repo, ref: opts.ref, root: opts.root },
|
||||
nav,
|
||||
docs,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,100 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
buildSnippet,
|
||||
highlight,
|
||||
searchDocs,
|
||||
toPlainText,
|
||||
type SearchDoc,
|
||||
} from "@portal/docs/search";
|
||||
|
||||
const DOCS: SearchDoc[] = [
|
||||
{
|
||||
id: "ocr",
|
||||
title: "OCR Guide",
|
||||
sectionLabel: "Configuration",
|
||||
text: "Stirling PDF uses Tesseract for its text recognition and language packs.",
|
||||
},
|
||||
{
|
||||
id: "docker",
|
||||
title: "Docker Install",
|
||||
sectionLabel: "Installation",
|
||||
text: "Run Stirling with docker compose up to start the container.",
|
||||
},
|
||||
{
|
||||
id: "ranky",
|
||||
title: "Something else",
|
||||
sectionLabel: "Misc",
|
||||
text: "docker docker docker appears many times in the body here.",
|
||||
},
|
||||
];
|
||||
|
||||
describe("toPlainText", () => {
|
||||
it("strips headings, links, inline code, and code fences", () => {
|
||||
const md =
|
||||
"# Title\n\nSee [the guide](doc:x) and run `npm i`.\n\n```bash\nnpm run build\n```";
|
||||
const out = toPlainText(md);
|
||||
expect(out).toContain("Title");
|
||||
expect(out).toContain("the guide");
|
||||
expect(out).toContain("npm i");
|
||||
expect(out).toContain("npm run build"); // code text kept, fences dropped
|
||||
expect(out).not.toContain("#");
|
||||
expect(out).not.toContain("```");
|
||||
expect(out).not.toContain("](");
|
||||
});
|
||||
});
|
||||
|
||||
describe("highlight", () => {
|
||||
it("splits text into hit/non-hit segments", () => {
|
||||
expect(highlight("Hello world", ["world"])).toEqual([
|
||||
{ text: "Hello ", hit: false },
|
||||
{ text: "world", hit: true },
|
||||
]);
|
||||
});
|
||||
|
||||
it("is safe against regex metacharacters in terms", () => {
|
||||
expect(() => highlight("a (b) c", ["("])).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildSnippet", () => {
|
||||
it("windows around the first match and marks it", () => {
|
||||
const text =
|
||||
"lorem ipsum ".repeat(20) + "the TARGET keyword " + "dolor ".repeat(20);
|
||||
const segs = buildSnippet(text, ["target"]);
|
||||
expect(segs.some((s) => s.hit && /target/i.test(s.text))).toBe(true);
|
||||
// Windowed, so it should be far shorter than the full text.
|
||||
expect(segs.map((s) => s.text).join("").length).toBeLessThan(text.length);
|
||||
});
|
||||
});
|
||||
|
||||
describe("searchDocs", () => {
|
||||
it("returns nothing for an empty query", () => {
|
||||
expect(searchDocs(DOCS, " ")).toEqual([]);
|
||||
});
|
||||
|
||||
it("matches body content, not just titles (with a snippet)", () => {
|
||||
const res = searchDocs(DOCS, "tesseract");
|
||||
expect(res.map((r) => r.id)).toEqual(["ocr"]);
|
||||
expect(res[0].snippet.some((s) => s.hit && /tesseract/i.test(s.text))).toBe(
|
||||
true,
|
||||
);
|
||||
});
|
||||
|
||||
it("ranks title matches above body matches", () => {
|
||||
const res = searchDocs(DOCS, "docker");
|
||||
// "Docker Install" (title hit) outranks "Something else" (body-only hits).
|
||||
expect(res[0].id).toBe("docker");
|
||||
expect(res.map((r) => r.id)).toContain("ranky");
|
||||
});
|
||||
|
||||
it("requires every term to match (AND)", () => {
|
||||
expect(searchDocs(DOCS, "docker compose").map((r) => r.id)).toEqual([
|
||||
"docker",
|
||||
]);
|
||||
expect(searchDocs(DOCS, "docker tesseract")).toEqual([]);
|
||||
});
|
||||
|
||||
it("does not throw on regex-special-character queries", () => {
|
||||
expect(() => searchDocs(DOCS, "a(b")).not.toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,153 @@
|
||||
/**
|
||||
* Full-text search over the docs manifest. Pure + dependency-free so it's unit
|
||||
* testable. Indexes each doc's title + plaintext body; ranks title matches above
|
||||
* body matches; returns highlighted title + a content snippet per hit.
|
||||
*/
|
||||
|
||||
export interface SearchDoc {
|
||||
id: string;
|
||||
title: string;
|
||||
sectionLabel: string;
|
||||
/** Plaintext body (markdown stripped), original case. */
|
||||
text: string;
|
||||
}
|
||||
|
||||
/** A run of result text, flagged when it matches a query term (for <mark>). */
|
||||
export interface Segment {
|
||||
text: string;
|
||||
hit: boolean;
|
||||
}
|
||||
|
||||
export interface SearchResult {
|
||||
id: string;
|
||||
title: string;
|
||||
sectionLabel: string;
|
||||
titleSegments: Segment[];
|
||||
snippet: Segment[];
|
||||
score: number;
|
||||
}
|
||||
|
||||
/** Strip markdown/MDX down to readable plaintext for indexing + snippets. */
|
||||
export function toPlainText(md: string): string {
|
||||
return md
|
||||
.replace(/^(```|~~~).*$/gm, " ") // fence delimiters (keep the code text)
|
||||
.replace(/`([^`]+)`/g, "$1") // inline code
|
||||
.replace(/!\[[^\]]*\]\([^)]*\)/g, " ") // images
|
||||
.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links → their text
|
||||
.replace(/^\s{0,3}>\s?/gm, "") // blockquotes
|
||||
.replace(/^\s{0,3}#{1,6}\s+/gm, "") // headings
|
||||
.replace(/^\s*[-*+]\s+/gm, "") // list bullets
|
||||
.replace(/[*_~]/g, "") // emphasis marks
|
||||
.replace(/\|/g, " ") // table pipes
|
||||
.replace(/\s+/g, " ") // collapse whitespace
|
||||
.trim();
|
||||
}
|
||||
|
||||
function escapeRegExp(s: string): string {
|
||||
return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||
}
|
||||
|
||||
function countOccurrences(haystack: string, needle: string): number {
|
||||
let count = 0;
|
||||
let i = haystack.indexOf(needle);
|
||||
while (i !== -1) {
|
||||
count++;
|
||||
i = haystack.indexOf(needle, i + needle.length);
|
||||
}
|
||||
return count;
|
||||
}
|
||||
|
||||
/** Split `text` into segments, flagging any run that matches a query term. */
|
||||
export function highlight(text: string, terms: string[]): Segment[] {
|
||||
const cleaned = terms.map(escapeRegExp).filter(Boolean);
|
||||
if (!cleaned.length) return [{ text, hit: false }];
|
||||
const re = new RegExp(`(${cleaned.join("|")})`, "gi");
|
||||
const segments: Segment[] = [];
|
||||
let last = 0;
|
||||
let m: RegExpExecArray | null;
|
||||
while ((m = re.exec(text)) !== null) {
|
||||
if (m.index > last) {
|
||||
segments.push({ text: text.slice(last, m.index), hit: false });
|
||||
}
|
||||
segments.push({ text: m[0], hit: true });
|
||||
last = m.index + m[0].length;
|
||||
if (m.index === re.lastIndex) re.lastIndex++; // guard against zero-width
|
||||
}
|
||||
if (last < text.length) segments.push({ text: text.slice(last), hit: false });
|
||||
return segments.length ? segments : [{ text, hit: false }];
|
||||
}
|
||||
|
||||
/** Build a ~context-window snippet around the earliest term match. */
|
||||
export function buildSnippet(
|
||||
text: string,
|
||||
terms: string[],
|
||||
radius = 90,
|
||||
): Segment[] {
|
||||
const lower = text.toLowerCase();
|
||||
let pos = -1;
|
||||
for (const term of terms) {
|
||||
const i = lower.indexOf(term);
|
||||
if (i !== -1 && (pos === -1 || i < pos)) pos = i;
|
||||
}
|
||||
if (pos === -1) {
|
||||
const head = text.slice(0, radius * 2);
|
||||
return highlight(head + (text.length > head.length ? "…" : ""), terms);
|
||||
}
|
||||
let start = Math.max(0, pos - radius);
|
||||
let end = Math.min(text.length, pos + radius);
|
||||
// Snap to word boundaries so we don't slice mid-word.
|
||||
if (start > 0) {
|
||||
const space = text.indexOf(" ", start);
|
||||
if (space !== -1 && space < pos) start = space + 1;
|
||||
}
|
||||
if (end < text.length) {
|
||||
const space = text.lastIndexOf(" ", end);
|
||||
if (space > pos) end = space;
|
||||
}
|
||||
let snippet = text.slice(start, end).trim();
|
||||
if (start > 0) snippet = "…" + snippet;
|
||||
if (end < text.length) snippet = snippet + "…";
|
||||
return highlight(snippet, terms);
|
||||
}
|
||||
|
||||
/**
|
||||
* Rank docs against a query. A doc matches when every term appears in its title
|
||||
* or body; title hits score highest.
|
||||
*/
|
||||
export function searchDocs(
|
||||
docs: SearchDoc[],
|
||||
query: string,
|
||||
limit = 40,
|
||||
): SearchResult[] {
|
||||
const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
|
||||
if (!terms.length) return [];
|
||||
|
||||
const results: SearchResult[] = [];
|
||||
for (const doc of docs) {
|
||||
const titleLower = doc.title.toLowerCase();
|
||||
const textLower = doc.text.toLowerCase();
|
||||
const matchesAll = terms.every(
|
||||
(term) => titleLower.includes(term) || textLower.includes(term),
|
||||
);
|
||||
if (!matchesAll) continue;
|
||||
|
||||
let score = 0;
|
||||
for (const term of terms) {
|
||||
if (titleLower.includes(term)) score += 10;
|
||||
if (titleLower.startsWith(term)) score += 5;
|
||||
score += Math.min(countOccurrences(textLower, term), 5);
|
||||
}
|
||||
|
||||
results.push({
|
||||
id: doc.id,
|
||||
title: doc.title,
|
||||
sectionLabel: doc.sectionLabel,
|
||||
titleSegments: highlight(doc.title, terms),
|
||||
snippet: buildSnippet(doc.text, terms),
|
||||
score,
|
||||
});
|
||||
}
|
||||
|
||||
results.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));
|
||||
return results.slice(0, limit);
|
||||
}
|
||||
File diff suppressed because one or more lines are too long
@@ -1,73 +1,254 @@
|
||||
/* Full-height docs surface: the sidebar and reading pane each scroll on their
|
||||
own inside the portal shell's scroll container, so a 70+ item nav no longer
|
||||
drags the whole page around. */
|
||||
.portal-docs {
|
||||
display: grid;
|
||||
grid-template-columns: 15rem minmax(0, 1fr);
|
||||
gap: 2rem;
|
||||
padding: 1.5rem;
|
||||
max-width: 84rem;
|
||||
margin: 0 auto;
|
||||
align-items: start;
|
||||
grid-template-columns: 16rem minmax(0, 1fr);
|
||||
height: 100%;
|
||||
min-height: 0;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
@media (max-width: 60rem) {
|
||||
.portal-docs {
|
||||
grid-template-columns: 1fr;
|
||||
gap: 1.25rem;
|
||||
/* With an "On this page" TOC, add a right-hand column. */
|
||||
.portal-docs--with-toc {
|
||||
grid-template-columns: 16rem minmax(0, 1fr) 15rem;
|
||||
}
|
||||
|
||||
/* Not enough room for three columns → drop the TOC. */
|
||||
@media (max-width: 72rem) {
|
||||
.portal-docs--with-toc {
|
||||
grid-template-columns: 16rem minmax(0, 1fr);
|
||||
}
|
||||
.portal-docs__toc-col {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
/* ── Left nav ──────────────────────────────────────────────────────────── */
|
||||
.portal-docs--empty {
|
||||
display: block;
|
||||
padding: 3rem 1.5rem;
|
||||
}
|
||||
|
||||
/* ── Left nav (own scroll column) ──────────────────────────────────────── */
|
||||
|
||||
.portal-docs__sidebar {
|
||||
position: sticky;
|
||||
top: 1.5rem;
|
||||
align-self: start;
|
||||
}
|
||||
|
||||
@media (max-width: 60rem) {
|
||||
.portal-docs__sidebar {
|
||||
position: static;
|
||||
}
|
||||
min-height: 0;
|
||||
height: 100%;
|
||||
overflow-y: auto;
|
||||
border-right: 1px solid var(--color-border-light);
|
||||
padding: 1.25rem 0;
|
||||
}
|
||||
|
||||
.portal-docs__nav {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 1.25rem;
|
||||
gap: 0.25rem;
|
||||
}
|
||||
|
||||
/* Search */
|
||||
.portal-docs__search {
|
||||
margin-bottom: 0.75rem;
|
||||
padding: 0 0.75rem;
|
||||
}
|
||||
|
||||
.portal-docs__search-box {
|
||||
position: relative;
|
||||
}
|
||||
|
||||
.portal-docs__search-icon {
|
||||
position: absolute;
|
||||
left: 0.625rem;
|
||||
top: 50%;
|
||||
transform: translateY(-50%);
|
||||
font-size: 0.9375rem;
|
||||
color: var(--color-text-4);
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.portal-docs__search-input {
|
||||
width: 100%;
|
||||
padding: 0.4rem 0.6rem 0.4rem 1.9rem;
|
||||
font-size: 0.8125rem;
|
||||
color: var(--color-text-1);
|
||||
background: var(--color-bg-subtle);
|
||||
border: 1px solid var(--color-border-light);
|
||||
border-radius: var(--radius-md);
|
||||
outline: none;
|
||||
}
|
||||
|
||||
.portal-docs__search-input:focus {
|
||||
border-color: var(--color-blue);
|
||||
}
|
||||
|
||||
.portal-docs__nav-empty {
|
||||
font-size: 0.8125rem;
|
||||
color: var(--color-text-4);
|
||||
padding: 0.5rem 0.75rem;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
/* ── Search results ────────────────────────────────────────────────────── */
|
||||
|
||||
.portal-docs__results {
|
||||
margin-top: 0.5rem;
|
||||
}
|
||||
|
||||
.portal-docs__results-count {
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 500;
|
||||
color: var(--color-text-4);
|
||||
padding: 0 0.75rem 0.5rem;
|
||||
}
|
||||
|
||||
.portal-docs__results-list {
|
||||
list-style: none;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
}
|
||||
|
||||
/* Hairline divider between results for clear, calm separation. */
|
||||
.portal-docs__results-list li + li {
|
||||
border-top: 1px solid var(--color-border-light);
|
||||
}
|
||||
|
||||
.portal-docs__result {
|
||||
height: auto;
|
||||
padding: 0.5rem 0.75rem;
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.portal-docs__result:hover,
|
||||
.portal-docs__result.is-active {
|
||||
background: var(--color-bg-hover);
|
||||
}
|
||||
|
||||
.portal-docs__result-body {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.125rem;
|
||||
width: 100%;
|
||||
min-width: 0;
|
||||
text-align: left;
|
||||
white-space: normal;
|
||||
}
|
||||
|
||||
/* Title + section share one line; the title truncates before the section. */
|
||||
.portal-docs__result-head {
|
||||
display: flex;
|
||||
align-items: baseline;
|
||||
gap: 0.4rem;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.portal-docs__result-title {
|
||||
font-size: 0.8125rem;
|
||||
font-weight: 600;
|
||||
color: var(--color-text-1);
|
||||
line-height: 1.3;
|
||||
min-width: 0;
|
||||
overflow: hidden;
|
||||
white-space: nowrap;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.portal-docs__result-section {
|
||||
flex-shrink: 0;
|
||||
font-size: 0.6875rem;
|
||||
color: var(--color-text-4);
|
||||
}
|
||||
|
||||
.portal-docs__result-snippet {
|
||||
font-size: 0.75rem;
|
||||
line-height: 1.4;
|
||||
color: var(--color-text-4);
|
||||
display: -webkit-box;
|
||||
-webkit-line-clamp: 1;
|
||||
-webkit-box-orient: vertical;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
/* Subtle match emphasis — coloured text, not a filled block. */
|
||||
.portal-docs__hl {
|
||||
color: var(--color-blue);
|
||||
font-weight: 600;
|
||||
background: none;
|
||||
}
|
||||
|
||||
.portal-docs__nav-group {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.375rem;
|
||||
gap: 0.0625rem;
|
||||
}
|
||||
|
||||
/* Section label: shared typography for the static Overview label and the
|
||||
collapsible accordion headers below. */
|
||||
.portal-docs__nav-head {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
padding: 0.4rem 0.75rem 0.2rem;
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.06em;
|
||||
text-transform: uppercase;
|
||||
color: var(--color-text-4);
|
||||
padding: 0 0.5rem;
|
||||
}
|
||||
|
||||
.portal-docs__nav-icon {
|
||||
display: inline-flex;
|
||||
/* Collapsible section header (Overview stays a static label). */
|
||||
.portal-docs__nav-head--button:hover {
|
||||
background: var(--color-bg-hover);
|
||||
color: var(--color-text-2);
|
||||
}
|
||||
|
||||
.portal-docs__nav-head-main {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 1.125rem;
|
||||
height: 1.125rem;
|
||||
font-size: 0.6875rem;
|
||||
border-radius: var(--radius-sm);
|
||||
gap: 0.4rem;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.portal-docs__nav-headlabel {
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.portal-docs__nav-chevron {
|
||||
font-size: 0.625rem;
|
||||
color: var(--color-text-4);
|
||||
transition: transform var(--motion-fast);
|
||||
}
|
||||
|
||||
.portal-docs__nav-chevron.is-open {
|
||||
transform: rotate(90deg);
|
||||
}
|
||||
|
||||
.portal-docs__nav-count {
|
||||
font-size: 0.625rem;
|
||||
font-weight: 600;
|
||||
color: var(--color-text-4);
|
||||
background: var(--color-bg-subtle);
|
||||
color: var(--color-text-3);
|
||||
border-radius: var(--radius-pill);
|
||||
padding: 0.05rem 0.4rem;
|
||||
}
|
||||
|
||||
/* Space consecutive sections apart (not before the first). */
|
||||
.portal-docs__nav-group + .portal-docs__nav-group {
|
||||
margin-top: 0.4rem;
|
||||
}
|
||||
|
||||
/* Nested sub-sections: indented under their parent with a guide line. */
|
||||
.portal-docs__nav-children {
|
||||
margin: 0.125rem 0 0.25rem 0.85rem;
|
||||
padding-left: 0.4rem;
|
||||
border-left: 1px solid var(--color-border-light);
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.0625rem;
|
||||
}
|
||||
|
||||
.portal-docs__nav-list {
|
||||
list-style: none;
|
||||
margin: 0;
|
||||
margin: 0 0 0.375rem;
|
||||
padding: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
@@ -80,10 +261,10 @@
|
||||
justify-content: space-between;
|
||||
gap: 0.5rem;
|
||||
width: 100%;
|
||||
padding: 0.375rem 0.5rem;
|
||||
padding: 0.35rem 0.75rem;
|
||||
border: none;
|
||||
background: transparent;
|
||||
border-radius: var(--radius-md);
|
||||
border-radius: 0;
|
||||
font-size: 0.8125rem;
|
||||
color: var(--color-text-3);
|
||||
cursor: pointer;
|
||||
@@ -110,10 +291,129 @@
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
/* ── Content shell ─────────────────────────────────────────────────────── */
|
||||
/* Mobile-only nav toggle (a drawer button); hidden on desktop. */
|
||||
.portal-docs__nav-toggle {
|
||||
display: none;
|
||||
}
|
||||
|
||||
/* ── Reading pane (own scroll column) ──────────────────────────────────── */
|
||||
|
||||
.portal-docs__content {
|
||||
min-width: 0;
|
||||
min-height: 0;
|
||||
height: 100%;
|
||||
overflow-y: auto;
|
||||
padding: 1.5rem 2rem 4rem;
|
||||
}
|
||||
|
||||
.portal-docs__content-inner {
|
||||
max-width: 46rem;
|
||||
margin: 0 auto;
|
||||
}
|
||||
|
||||
/* ── On this page (right rail) ─────────────────────────────────────────── */
|
||||
|
||||
.portal-docs__toc-col {
|
||||
min-height: 0;
|
||||
height: 100%;
|
||||
overflow-y: auto;
|
||||
border-left: 1px solid var(--color-border-light);
|
||||
padding: 1.5rem 0.75rem;
|
||||
}
|
||||
|
||||
.portal-docs__toc {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
}
|
||||
|
||||
.portal-docs__toc-title {
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.06em;
|
||||
text-transform: uppercase;
|
||||
color: var(--color-text-4);
|
||||
padding: 0 0.5rem 0.5rem;
|
||||
}
|
||||
|
||||
.portal-docs__toc-list {
|
||||
list-style: none;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.0625rem;
|
||||
}
|
||||
|
||||
.portal-docs__toc-link {
|
||||
display: block;
|
||||
padding: 0.25rem 0.5rem;
|
||||
border-left: 2px solid transparent;
|
||||
font-size: 0.8125rem;
|
||||
line-height: 1.35;
|
||||
color: var(--color-text-3);
|
||||
text-decoration: none;
|
||||
transition: color var(--motion-fast);
|
||||
}
|
||||
|
||||
.portal-docs__toc-link.is-sub {
|
||||
padding-left: 1.25rem;
|
||||
font-size: 0.75rem;
|
||||
}
|
||||
|
||||
.portal-docs__toc-link:hover {
|
||||
color: var(--color-text-1);
|
||||
}
|
||||
|
||||
.portal-docs__toc-link.is-active {
|
||||
color: var(--color-blue);
|
||||
border-left-color: var(--color-blue);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
/* Scroll-to-heading lands just below the pane top, not flush against it. */
|
||||
.portal-docs__md h2,
|
||||
.portal-docs__md h3 {
|
||||
scroll-margin-top: 1rem;
|
||||
}
|
||||
|
||||
/* ── Small screens: nav collapses into a drawer above the content ──────── */
|
||||
|
||||
@media (max-width: 60rem) {
|
||||
.portal-docs {
|
||||
grid-template-columns: 1fr;
|
||||
grid-template-rows: auto auto minmax(0, 1fr);
|
||||
}
|
||||
|
||||
.portal-docs__nav-toggle {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
margin: 0.75rem 1rem 0;
|
||||
padding: 0.5rem 0.75rem;
|
||||
font-size: 0.8125rem;
|
||||
font-weight: 600;
|
||||
color: var(--color-text-1);
|
||||
background: var(--color-bg-subtle);
|
||||
border: 1px solid var(--color-border-light);
|
||||
border-radius: var(--radius-md);
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.portal-docs__sidebar {
|
||||
display: none;
|
||||
height: auto;
|
||||
max-height: 60vh;
|
||||
border-right: none;
|
||||
border-bottom: 1px solid var(--color-border-light);
|
||||
}
|
||||
|
||||
.portal-docs__sidebar.is-open {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.portal-docs__content {
|
||||
padding: 1.25rem 1.25rem 3rem;
|
||||
}
|
||||
}
|
||||
|
||||
.portal-docs__section {
|
||||
@@ -523,3 +823,160 @@
|
||||
font-size: 0.75rem;
|
||||
color: var(--color-text-4);
|
||||
}
|
||||
|
||||
/* ── Markdown content ──────────────────────────────────────────────────── */
|
||||
|
||||
.portal-docs__md {
|
||||
font-size: 0.9375rem;
|
||||
line-height: 1.65;
|
||||
color: var(--color-text-2);
|
||||
}
|
||||
|
||||
.portal-docs__md h1,
|
||||
.portal-docs__md h2,
|
||||
.portal-docs__md h3,
|
||||
.portal-docs__md h4 {
|
||||
color: var(--color-text-1);
|
||||
font-weight: 650;
|
||||
line-height: 1.25;
|
||||
margin: 1.75rem 0 0.75rem;
|
||||
}
|
||||
|
||||
.portal-docs__md h2 {
|
||||
font-size: 1.3125rem;
|
||||
padding-bottom: 0.3rem;
|
||||
border-bottom: 1px solid var(--color-border-light);
|
||||
}
|
||||
|
||||
.portal-docs__md h3 {
|
||||
font-size: 1.0625rem;
|
||||
}
|
||||
|
||||
.portal-docs__md h4 {
|
||||
font-size: 0.9375rem;
|
||||
}
|
||||
|
||||
.portal-docs__md > :first-child {
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
.portal-docs__md p,
|
||||
.portal-docs__md ul,
|
||||
.portal-docs__md ol {
|
||||
margin: 0 0 0.875rem;
|
||||
}
|
||||
|
||||
.portal-docs__md li {
|
||||
margin: 0.25rem 0;
|
||||
}
|
||||
|
||||
.portal-docs__md a {
|
||||
color: var(--color-blue);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.portal-docs__md a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.portal-docs__md code {
|
||||
font-family: var(--font-mono, monospace);
|
||||
font-size: 0.85em;
|
||||
background: var(--color-bg-subtle);
|
||||
padding: 0.1em 0.35em;
|
||||
border-radius: var(--radius-sm);
|
||||
}
|
||||
|
||||
.portal-docs__md blockquote {
|
||||
margin: 0 0 0.875rem;
|
||||
padding: 0.125rem 0.875rem;
|
||||
border-left: 3px solid var(--color-blue);
|
||||
background: var(--color-bg-subtle);
|
||||
border-radius: 0 var(--radius-md) var(--radius-md) 0;
|
||||
color: var(--color-text-3);
|
||||
}
|
||||
|
||||
.portal-docs__md blockquote p {
|
||||
margin: 0.5rem 0;
|
||||
}
|
||||
|
||||
.portal-docs__md-img {
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
border-radius: var(--radius-md);
|
||||
border: 1px solid var(--color-border-light);
|
||||
}
|
||||
|
||||
.portal-docs__md hr {
|
||||
border: none;
|
||||
border-top: 1px solid var(--color-border-light);
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
|
||||
.portal-docs__md-pre {
|
||||
position: relative;
|
||||
margin: 0 0 0.875rem;
|
||||
}
|
||||
|
||||
.portal-docs__md-pre pre {
|
||||
margin: 0;
|
||||
padding: 0.875rem 4rem 0.875rem 0.875rem;
|
||||
background: var(--color-bg-subtle);
|
||||
border: 1px solid var(--color-border-light);
|
||||
border-radius: var(--radius-md);
|
||||
overflow-x: auto;
|
||||
font-size: 0.8125rem;
|
||||
line-height: 1.5;
|
||||
}
|
||||
|
||||
.portal-docs__md-pre pre code {
|
||||
background: none;
|
||||
padding: 0;
|
||||
font-size: inherit;
|
||||
}
|
||||
|
||||
.portal-docs__md-copy {
|
||||
position: absolute;
|
||||
top: 0.5rem;
|
||||
right: 0.5rem;
|
||||
}
|
||||
|
||||
.portal-docs__md-tablewrap {
|
||||
overflow-x: auto;
|
||||
margin: 0 0 0.875rem;
|
||||
}
|
||||
|
||||
.portal-docs__md-tablewrap table {
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
font-size: 0.8125rem;
|
||||
}
|
||||
|
||||
.portal-docs__md-tablewrap th,
|
||||
.portal-docs__md-tablewrap td {
|
||||
border: 1px solid var(--color-border-light);
|
||||
padding: 0.4rem 0.625rem;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.portal-docs__md-tablewrap th {
|
||||
background: var(--color-bg-subtle);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.portal-docs__source {
|
||||
margin-top: 2rem;
|
||||
padding-top: 1rem;
|
||||
border-top: 1px solid var(--color-border-light);
|
||||
font-size: 0.8125rem;
|
||||
}
|
||||
|
||||
.portal-docs__source a {
|
||||
color: var(--color-text-3);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.portal-docs__source a:hover {
|
||||
color: var(--color-blue);
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
import type { Meta, StoryObj } from "@storybook/react-vite";
|
||||
import { DeveloperDocs } from "@portal/views/DeveloperDocs";
|
||||
|
||||
// Renders the real docs manifest (generated by scripts/sync-portal-docs.mts), so
|
||||
// this story is a live view of the auto-built Documentation browser. The view
|
||||
// fills its container's height (independent sidebar/content scroll), so the
|
||||
// decorator gives it a viewport-height frame.
|
||||
const meta: Meta<typeof DeveloperDocs> = {
|
||||
title: "Portal/DeveloperDocs/View",
|
||||
component: DeveloperDocs,
|
||||
parameters: { layout: "fullscreen" },
|
||||
decorators: [
|
||||
(Story) => (
|
||||
<div style={{ height: "100vh" }}>
|
||||
<Story />
|
||||
</div>
|
||||
),
|
||||
],
|
||||
};
|
||||
export default meta;
|
||||
|
||||
type Story = StoryObj<typeof DeveloperDocs>;
|
||||
|
||||
export const Default: Story = {};
|
||||
@@ -0,0 +1,80 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { fireEvent, render, screen, waitFor } from "@testing-library/react";
|
||||
import { MantineProvider } from "@mantine/core";
|
||||
import { MemoryRouter } from "react-router-dom";
|
||||
import type { ReactElement } from "react";
|
||||
|
||||
// Deterministic labels; the view + DocsNav + MarkdownDoc all use useTranslation.
|
||||
vi.mock("react-i18next", () => ({
|
||||
useTranslation: () => ({
|
||||
// 2nd arg may be a default string or i18next interpolation options ({count}).
|
||||
t: (key: string, opts?: unknown) => (typeof opts === "string" ? opts : key),
|
||||
i18n: { changeLanguage: vi.fn() },
|
||||
}),
|
||||
}));
|
||||
|
||||
import { DeveloperDocs } from "@portal/views/DeveloperDocs";
|
||||
|
||||
const renderDocs = (ui: ReactElement) =>
|
||||
render(
|
||||
<MemoryRouter initialEntries={["/processor/docs"]}>
|
||||
<MantineProvider>{ui}</MantineProvider>
|
||||
</MemoryRouter>,
|
||||
);
|
||||
|
||||
describe("DeveloperDocs — markdown browser over the generated manifest", () => {
|
||||
it("keeps Overview static (open, no toggle) and other sections collapsed", () => {
|
||||
renderDocs(<DeveloperDocs />);
|
||||
expect(screen.getByRole("searchbox")).toBeInTheDocument();
|
||||
// Overview is static: its items show, and it has no toggle button.
|
||||
expect(
|
||||
screen.getByRole("button", { name: "Production Deployment Guide" }),
|
||||
).toBeInTheDocument();
|
||||
expect(
|
||||
screen.queryByRole("button", { name: /^Overview/i }),
|
||||
).not.toBeInTheDocument();
|
||||
// Other sections collapse, so their items are hidden until expanded.
|
||||
expect(
|
||||
screen.queryByRole("button", { name: "Kubernetes Guide" }),
|
||||
).not.toBeInTheDocument();
|
||||
expect(
|
||||
screen.getByText(/locally hosted web application/i),
|
||||
).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it("expands a collapsible section when its header is clicked", () => {
|
||||
renderDocs(<DeveloperDocs />);
|
||||
fireEvent.click(screen.getByRole("button", { name: /Installation/i }));
|
||||
expect(
|
||||
screen.getByRole("button", { name: "Kubernetes Guide" }),
|
||||
).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it("searches doc content (not just titles), shows a snippet, and navigates", async () => {
|
||||
renderDocs(<DeveloperDocs />);
|
||||
// "Tesseract" appears in the OCR doc body but in no doc title — a result
|
||||
// whose snippet contains it proves full-text (content) search.
|
||||
fireEvent.change(screen.getByRole("searchbox"), {
|
||||
target: { value: "Tesseract" },
|
||||
});
|
||||
const hits = await screen.findAllByRole("button", { name: /Tesseract/i });
|
||||
expect(hits.length).toBeGreaterThan(0);
|
||||
fireEvent.click(hits[0]);
|
||||
await waitFor(() =>
|
||||
expect(
|
||||
screen.queryByText(/locally hosted web application/i),
|
||||
).not.toBeInTheDocument(),
|
||||
);
|
||||
});
|
||||
|
||||
it("follows an internal doc: link inside the rendered markdown", async () => {
|
||||
renderDocs(<DeveloperDocs />);
|
||||
// The Getting Started body links to the Migration guide via the doc: scheme.
|
||||
fireEvent.click(screen.getByRole("link", { name: /Migration Guide/i }));
|
||||
await waitFor(() =>
|
||||
expect(
|
||||
screen.queryByText(/locally hosted web application/i),
|
||||
).not.toBeInTheDocument(),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,97 +1,140 @@
|
||||
import { useState } from "react";
|
||||
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
||||
import { useTranslation } from "react-i18next";
|
||||
import { EmptyState } from "@app/ui";
|
||||
import { useTier } from "@portal/contexts/TierContext";
|
||||
import { useAsync, useSectionFlags } from "@portal/hooks/useAsync";
|
||||
import { useLocation, useNavigate } from "react-router-dom";
|
||||
import { Button, EmptyState } from "@app/ui";
|
||||
import { DocsNav } from "@portal/components/docs/DocsNav";
|
||||
import { DocsSearch } from "@portal/components/docs/DocsSearch";
|
||||
import { DocsSection } from "@portal/components/docs/DocsSection";
|
||||
import { DocsToc } from "@portal/components/docs/DocsToc";
|
||||
import { MarkdownDoc } from "@portal/components/docs/MarkdownDoc";
|
||||
import { extractHeadings } from "@portal/docs/headings";
|
||||
import {
|
||||
fetchDocsContent,
|
||||
fetchDocsNav,
|
||||
type DocsContent,
|
||||
type DocsNavSection,
|
||||
} from "@portal/api/docs";
|
||||
import { DocsNav, DocsNavSkeleton } from "@portal/components/docs/DocsNav";
|
||||
import { GettingStartedSection } from "@portal/components/docs/GettingStartedSection";
|
||||
import { AuthenticationSection } from "@portal/components/docs/AuthenticationSection";
|
||||
import { RateLimitsSection } from "@portal/components/docs/RateLimitsSection";
|
||||
import { EndpointReferenceSection } from "@portal/components/docs/EndpointReferenceSection";
|
||||
import { ErrorsSection } from "@portal/components/docs/ErrorsSection";
|
||||
import { WebhooksSection } from "@portal/components/docs/WebhooksSection";
|
||||
import { SdksSection } from "@portal/components/docs/SdksSection";
|
||||
import { ComponentsSection } from "@portal/components/docs/ComponentsSection";
|
||||
import { PlaybooksSection } from "@portal/components/docs/PlaybooksSection";
|
||||
import { SkillsSection } from "@portal/components/docs/SkillsSection";
|
||||
allDocs,
|
||||
firstDocId,
|
||||
loadDoc,
|
||||
loadDocsNav,
|
||||
} from "@portal/docs/manifest/registry";
|
||||
import { searchDocs, toPlainText, type SearchDoc } from "@portal/docs/search";
|
||||
import "@portal/views/DeveloperDocs.css";
|
||||
|
||||
/** Renders the content pane for the active nav leaf against fetched content. */
|
||||
function DocsContentPane({
|
||||
active,
|
||||
content,
|
||||
}: {
|
||||
active: string;
|
||||
content: DocsContent;
|
||||
}) {
|
||||
switch (active) {
|
||||
case "authentication":
|
||||
return <AuthenticationSection />;
|
||||
case "rate-limits":
|
||||
return <RateLimitsSection rateLimit={content.rateLimit} />;
|
||||
case "endpoints":
|
||||
return <EndpointReferenceSection />;
|
||||
case "errors":
|
||||
return <ErrorsSection errors={content.errors} />;
|
||||
case "webhooks":
|
||||
return <WebhooksSection />;
|
||||
case "sdk-overview":
|
||||
return <SdksSection sdks={content.sdks} />;
|
||||
case "component-library":
|
||||
return <ComponentsSection components={content.components} />;
|
||||
case "recipes":
|
||||
return <PlaybooksSection playbooks={content.playbooks} />;
|
||||
case "skill-catalog":
|
||||
return <SkillsSection skills={content.skills} />;
|
||||
default:
|
||||
return (
|
||||
<GettingStartedSection
|
||||
samples={content.quickstartSamples}
|
||||
response={content.quickstartResponse}
|
||||
/>
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Developer Docs — a markdown browser over the docs manifest generated from the
|
||||
* Stirling docs repo (see scripts/sync-portal-docs.mts). The nav is auto-sorted
|
||||
* from the repo's folders + frontmatter; content is the repo markdown, and the
|
||||
* search box does full-text search across every doc.
|
||||
*/
|
||||
export function DeveloperDocs() {
|
||||
const { t } = useTranslation();
|
||||
const { tier } = useTier();
|
||||
const [active, setActive] = useState("quickstart");
|
||||
const { hash } = useLocation();
|
||||
const navigate = useNavigate();
|
||||
const contentRef = useRef<HTMLElement>(null);
|
||||
const [navOpen, setNavOpen] = useState(false);
|
||||
const [query, setQuery] = useState("");
|
||||
|
||||
const navState = useAsync<DocsNavSection[]>(() => fetchDocsNav(), []);
|
||||
const { data: nav } = navState;
|
||||
const { isLoading, isEmpty } = useSectionFlags(navState);
|
||||
const nav = useMemo(() => loadDocsNav(), []);
|
||||
const fallback = useMemo(() => firstDocId(), []);
|
||||
|
||||
const { data: content } = useAsync<DocsContent>(
|
||||
() => fetchDocsContent(tier),
|
||||
[tier],
|
||||
// Full-text index over every doc's plaintext body (built once).
|
||||
const index = useMemo<SearchDoc[]>(() => {
|
||||
const labels = new Map(nav.map((s) => [s.id, s.label]));
|
||||
return allDocs().map((d) => ({
|
||||
id: d.id,
|
||||
title: d.title,
|
||||
sectionLabel: labels.get(d.section) ?? "",
|
||||
text: toPlainText(d.markdown),
|
||||
}));
|
||||
}, [nav]);
|
||||
const results = useMemo(() => searchDocs(index, query), [index, query]);
|
||||
const searching = query.trim().length > 0;
|
||||
|
||||
// Deep-link support: the active doc id lives in the URL hash.
|
||||
const hashId = decodeURIComponent(hash.replace(/^#/, ""));
|
||||
const activeId = hashId && loadDoc(hashId) ? hashId : fallback;
|
||||
const doc = activeId ? loadDoc(activeId) : undefined;
|
||||
const section = useMemo(
|
||||
() => nav.find((s) => s.items.some((i) => i.id === activeId)),
|
||||
[nav, activeId],
|
||||
);
|
||||
// "On this page" headings for the current doc.
|
||||
const headings = useMemo(
|
||||
() => (doc ? extractHeadings(doc.markdown) : []),
|
||||
[doc],
|
||||
);
|
||||
|
||||
// Navigating closes the mobile drawer, clears the search, and resets the pane.
|
||||
const onSelect = useCallback(
|
||||
(id: string) => {
|
||||
navigate({ hash: id });
|
||||
setNavOpen(false);
|
||||
setQuery("");
|
||||
},
|
||||
[navigate],
|
||||
);
|
||||
|
||||
useEffect(() => {
|
||||
contentRef.current?.scrollTo?.({ top: 0 });
|
||||
}, [activeId]);
|
||||
|
||||
if (nav.length === 0 || !doc) {
|
||||
return (
|
||||
<div className="portal-docs portal-docs--empty">
|
||||
<EmptyState
|
||||
title={t("portal.docs.nav.empty.title")}
|
||||
description={t("portal.docs.nav.empty.description")}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
const hasToc = headings.length > 0;
|
||||
|
||||
return (
|
||||
<div className="portal-docs">
|
||||
<aside className="portal-docs__sidebar">
|
||||
{isLoading && <DocsNavSkeleton />}
|
||||
{isEmpty && (
|
||||
<EmptyState
|
||||
size="compact"
|
||||
title={t("portal.docs.nav.empty.title")}
|
||||
description={t("portal.docs.nav.empty.description")}
|
||||
/>
|
||||
)}
|
||||
{nav && nav.length > 0 && (
|
||||
<DocsNav sections={nav} active={active} onSelect={setActive} />
|
||||
<div className={"portal-docs" + (hasToc ? " portal-docs--with-toc" : "")}>
|
||||
<Button
|
||||
variant="tertiary"
|
||||
className="portal-docs__nav-toggle"
|
||||
aria-expanded={navOpen}
|
||||
onClick={() => setNavOpen((open) => !open)}
|
||||
leftSection={<span aria-hidden>☰</span>}
|
||||
>
|
||||
{t("portal.docs.browse")}
|
||||
</Button>
|
||||
|
||||
<aside className={"portal-docs__sidebar" + (navOpen ? " is-open" : "")}>
|
||||
<DocsSearch
|
||||
query={query}
|
||||
onQueryChange={setQuery}
|
||||
results={results}
|
||||
onSelect={onSelect}
|
||||
/>
|
||||
{!searching && (
|
||||
<DocsNav sections={nav} active={activeId ?? ""} onSelect={onSelect} />
|
||||
)}
|
||||
</aside>
|
||||
|
||||
<main className="portal-docs__content">
|
||||
{content && <DocsContentPane active={active} content={content} />}
|
||||
<main className="portal-docs__content" ref={contentRef}>
|
||||
<div className="portal-docs__content-inner">
|
||||
<DocsSection
|
||||
id={doc.id}
|
||||
eyebrow={section?.label ?? ""}
|
||||
title={doc.title}
|
||||
lead={doc.description}
|
||||
>
|
||||
<MarkdownDoc markdown={doc.markdown} onNavigate={onSelect} />
|
||||
<div className="portal-docs__source">
|
||||
<a href={doc.editUrl} target="_blank" rel="noopener noreferrer">
|
||||
{t("portal.docs.viewSource")}
|
||||
</a>
|
||||
</div>
|
||||
</DocsSection>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
{hasToc && (
|
||||
<aside className="portal-docs__toc-col">
|
||||
<DocsToc headings={headings} scrollRef={contentRef} />
|
||||
</aside>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -83,6 +83,7 @@
|
||||
"web-vitals": "^5.1.0"
|
||||
},
|
||||
"scripts": {
|
||||
"docs:sync": "tsx editor/scripts/sync-portal-docs.mts",
|
||||
"update:minor": "node scripts/update-minor.js",
|
||||
"update:major": "npx npm-check-updates -u && npm install",
|
||||
"update:interactive": "npx npm-check-updates -i",
|
||||
|
||||
Reference in New Issue
Block a user