Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(docs): redesign the in-app documentation section

rubenluetke10-beepd6efee5f2fa5
diff --git a/jarvis/ui/web/frontend/src/components/docs/Callout.tsx b/jarvis/ui/web/frontend/src/components/docs/Callout.tsx
index eb677e5382..9dcd2e367b 100644
--- a/jarvis/ui/web/frontend/src/components/docs/Callout.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/Callout.tsx
@@ -1,30 +1,43 @@
import type { ReactNode } from "react";
-import { Info, AlertTriangle, Lightbulb, FileText } from "lucide-react";
+import { AlertTriangle, Info, Lightbulb, NotebookPen } from "lucide-react";
import { cn } from "@/lib/utils";
+import { useT } from "@/i18n";
export type CalloutType = "info" | "warning" | "tip" | "note";
-const VARIANTS: Record<CalloutType, { className: string; icon: typeof Info }> = {
+/*
+ * Every variant is built from theme tokens, so it reads in light and dark
+ * alike: a hairline in the status hue, a faint wash of the same hue, and the
+ * hue on the icon and label only. Body text stays at body ink.
+ */
+const VARIANTS: Record<
+ CalloutType,
+ { frame: string; tone: string; icon: typeof Info; label: string }
+> = {
+ note: {
+ frame: "border-border bg-secondary/40",
+ tone: "text-foreground-secondary",
+ icon: NotebookPen,
+ label: "docs_content.callout_note",
+ },
info: {
- className:
- "border-l-blue-500/60 bg-blue-500/10 text-blue-100",
+ frame: "border-accent/30 bg-accent-soft",
+ tone: "text-accent",
icon: Info,
- },
- warning: {
- className:
- "border-l-amber-500/60 bg-foreground/10 text-foreground",
- icon: AlertTriangle,
+ label: "docs_content.callout_info",
},
tip: {
- className:
- "border-l-emerald-500/60 bg-muted-foreground/10 text-muted-foreground",
+ frame: "border-success/30 bg-success/[0.06]",
+ tone: "text-success",
icon: Lightbulb,
+ label: "docs_content.callout_tip",
},
- note: {
- className:
- "border-l-slate-500/60 bg-slate-500/10 text-slate-100",
- icon: FileText,
+ warning: {
+ frame: "border-warning/35 bg-warning/[0.07]",
+ tone: "text-warning",
+ icon: AlertTriangle,
+ label: "docs_content.callout_warning",
},
};
@@ -37,39 +50,59 @@ interface Props {
* Admonition block for info/warning/tip/note.
*
* Activation: in Markdown via `> [!info]`, `> [!warning]`, `> [!tip]`,
- * `> [!note]` as the first tag inside a blockquote. A standard Markdown
- * blockquote without a tag stays a default blockquote (the note variant).
+ * `> [!note]` (and GitHub's `[!important]` / `[!caution]`) as the first tag
+ * inside a blockquote. A blockquote without a tag stays a plain blockquote.
*/
export function Callout({ type = "note", children }: Props) {
+ const t = useT();
const variant = VARIANTS[type];
const Icon = variant.icon;
return (
<aside
className={cn(
- "not-prose my-4 flex gap-3 rounded-md border-l-4 px-4 py-3 text-sm",
- variant.className,
+ "not-prose my-6 rounded-lg border px-4 py-3.5",
+ variant.frame,
)}
>
- <Icon className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
- <div className="flex-1 [&>p]:m-0 [&>p+p]:mt-2">{children}</div>
+ <div
+ className={cn(
+ "mb-1 flex items-center gap-2 text-sm font-semibold",
+ variant.tone,
+ )}
+ >
+ <Icon className="h-4 w-4 shrink-0" aria-hidden="true" />
+ {t(variant.label)}
+ </div>
+ <div className="text-base leading-6 text-foreground-secondary [&_a]:text-accent [&_a]:underline [&_a]:decoration-accent/40 [&_a]:underline-offset-2 [&_code]:rounded-sm [&_code]:bg-secondary [&_code]:px-1 [&_code]:font-mono [&_code]:text-sm [&_strong]:font-semibold [&_strong]:text-foreground-strong [&>p]:m-0 [&>p+p]:mt-2">
+ {children}
+ </div>
</aside>
);
}
+const TAG_ALIASES: Record<string, CalloutType> = {
+ info: "info",
+ important: "info",
+ warning: "warning",
+ caution: "warning",
+ tip: "tip",
+ note: "note",
+};
+
/**
- * Heuristic: looks at the first text node of a blockquote. If it
- * starts with ``[!info]``, ``[!warning]``, ``[!tip]``, or ``[!note]``
- * (GitHub Markdown convention), returns the type + the rest as children.
+ * Heuristic: looks at the first text node of a blockquote. If it starts
+ * with a GitHub-style tag such as ``[!info]`` or ``[!warning]``, returns the
+ * type + the rest as children.
*
* No match -> ``null``, the renderer falls back to a normal blockquote.
*/
export function parseCalloutTag(
text: string,
): { type: CalloutType; rest: string } | null {
- const m = text.match(/^\s*\[!(info|warning|tip|note)\]\s*/i);
+ const m = text.match(/^\s*\[!(info|important|warning|caution|tip|note)\]\s*/i);
if (!m) return null;
return {
- type: m[1].toLowerCase() as CalloutType,
+ type: TAG_ALIASES[m[1].toLowerCase()],
rest: text.slice(m[0].length),
};
}
diff --git a/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsx b/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsx
index 2bf93759fb..7d4bb4ad97 100644
--- a/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsx
@@ -145,48 +145,49 @@ export function CodeBlock({ language, code, chrome = true }: CodeBlockProps) {
<div
className={cn(
"not-prose group relative overflow-hidden",
- chrome && "my-4 rounded-md border border-border bg-muted/40",
+ chrome && "my-6 rounded-lg border border-border bg-card",
)}
>
- {/* Header-Bar */}
{chrome && (
- <div className="flex items-center justify-between border-b border-border/40 bg-muted/20 px-3 py-1">
- <span className="text-micro uppercase tracking-wider text-muted-foreground">
- {language || "text"}
- </span>
- <button
- type="button"
- onClick={handleCopy}
- className={cn(
- "rounded p-1 text-muted-foreground opacity-60 transition",
- "hover:bg-muted hover:text-foreground hover:opacity-100",
- "group-hover:opacity-100",
- )}
- title={t("docs_content.copy_code")}
- aria-label={
- copied ? t("docs_content.code_copied") : t("docs_content.copy_code")
- }
- >
- {copied ? (
- <Check className="h-3 w-3 text-muted-foreground" aria-hidden="true" />
- ) : (
- <Copy className="h-3 w-3" aria-hidden="true" />
- )}
- <span className="sr-only" aria-live="polite">
- {copied ? t("docs_content.code_copied") : ""}
+ <div className="flex h-9 items-center justify-between border-b border-border pl-4 pr-1.5">
+ <span className="font-mono text-xs text-muted-foreground">
+ {language || "text"}
</span>
- </button>
- </div>
+ <button
+ type="button"
+ onClick={handleCopy}
+ className={cn(
+ "inline-flex h-7 items-center gap-1.5 rounded-sm px-2 text-xs font-medium text-muted-foreground transition-colors",
+ "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ )}
+ title={t("docs_content.copy_code")}
+ aria-label={
+ copied ? t("docs_content.code_copied") : t("docs_content.copy_code")
+ }
+ >
+ {copied ? (
+ <Check className="h-3.5 w-3.5 text-success" aria-hidden="true" />
+ ) : (
+ <Copy className="h-3.5 w-3.5" aria-hidden="true" />
+ )}
+ <span aria-hidden="true">
+ {copied ? t("docs_content.code_copied") : t("docs_content.copy")}
+ </span>
+ <span className="sr-only" aria-live="polite">
+ {copied ? t("docs_content.code_copied") : ""}
+ </span>
+ </button>
+ </div>
)}
{/* Body — either Shiki HTML or plain text */}
{html ? (
<div
- className="overflow-x-auto px-3 py-2 text-xs leading-relaxed [&_pre]:m-0 [&_pre]:!bg-transparent"
+ className="overflow-x-auto px-4 py-3.5 font-mono text-sm leading-6 [&_pre]:m-0 [&_pre]:!bg-transparent [&_pre]:font-mono"
// sanitized by Shiki — our code is only rendered locally
dangerouslySetInnerHTML={{ __html: html }}
/>
) : (
- <pre className="m-0 overflow-x-auto px-3 py-2 text-xs leading-relaxed text-foreground/90">
+ <pre className="m-0 overflow-x-auto px-4 py-3.5 font-mono text-sm leading-6 text-foreground">
<code>{code}</code>
</pre>
)}
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocTypeBadge.tsx b/jarvis/ui/web/frontend/src/components/docs/DocTypeBadge.tsx
deleted file mode 100644
index db26e97dac..0000000000
--- a/jarvis/ui/web/frontend/src/components/docs/DocTypeBadge.tsx
+++ /dev/null
@@ -1,48 +0,0 @@
-import { cn } from "@/lib/utils";
-import type { DocDiataxis } from "@/hooks/useDocs";
-
-const DIATAXIS_VARIANTS: Record<DocDiataxis, string> = {
- tutorial:
- "bg-violet-500/15 text-violet-300 border-violet-500/30",
- howto:
- "bg-blue-500/15 text-blue-300 border-blue-500/30",
- reference:
- "bg-slate-500/15 text-slate-300 border-slate-500/30",
- explanation:
- "bg-muted-foreground/15 text-muted-foreground border-muted-foreground/30",
- troubleshooting:
- "bg-foreground/15 text-foreground border-foreground/30",
- adr:
- "bg-rose-500/15 text-rose-300 border-rose-500/30",
- unclassified:
- "bg-neutral-500/15 text-neutral-400 border-neutral-500/30",
-};
-
-const DIATAXIS_LABEL: Record<DocDiataxis, string> = {
- tutorial: "Tutorial",
- howto: "How-To",
- reference: "Reference",
- explanation: "Concept",
- troubleshooting: "Trouble",
- adr: "ADR",
- unclassified: "Legacy",
-};
-
-interface Props {
- diataxis: DocDiataxis;
- className?: string;
-}
-
-export function DocTypeBadge({ diataxis, className }: Props) {
- return (
- <span
- className={cn(
- "inline-flex items-center rounded-md border px-1.5 py-0.5 text-micro font-medium uppercase tracking-wide",
- DIATAXIS_VARIANTS[diataxis],
- className,
- )}
- >
- {DIATAXIS_LABEL[diataxis]}
- </span>
- );
-}
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsx
index 14f7867ab1..78eace82c6 100644
--- a/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsx
@@ -76,4 +76,51 @@ describe("DocsContent", () => {
expect(openSpy).toHaveBeenCalledWith("https://personaljarvis.ai/docs/");
});
+ it("labels callouts and shows the reading time from tokens, not raw colours", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.includes("/api/docs/grouped")) {
+ return new Response(JSON.stringify({}), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ }
+ return new Response(
+ JSON.stringify({
+ title: "Keys",
+ slug: "keys",
+ diataxis: "howto",
+ summary: "Keep keys safe.",
+ section: "Privacy",
+ section_order: 1,
+ order: 1,
+ tags: [],
+ related: [],
+ last_reviewed: null,
+ path: "docs/product/keys.md",
+ body: "> [!warning] Never say a key out loud.",
+ headings: [],
+ }),
+ { status: 200, headers: { "Content-Type": "application/json" } },
+ );
+ }),
+ );
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false, gcTime: 0 } },
+ });
+
+ render(
+ <QueryClientProvider client={client}>
+ <DocsContent slug="keys" onSelect={() => {}} onShowOverview={() => {}} />
+ </QueryClientProvider>,
+ );
+
+ const label = await waitFor(() => screen.getByText("Warning"));
+ const callout = label.closest("aside");
+ expect(callout?.textContent).toContain("Never say a key out loud.");
+ expect(callout?.className).toContain("border-warning");
+ expect(screen.getByText("1 min read")).toBeTruthy();
+ });
});
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsx
index 032e0720b9..e5f91b486a 100644
--- a/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsx
@@ -1,11 +1,12 @@
-import { useMemo } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
import type { Components } from "react-markdown";
import {
+ ArrowLeft,
+ ArrowRight,
+ Check,
+ Copy,
+ ExternalLink,
FileWarning,
- ChevronLeft,
- ChevronRight,
- Clock,
- Link2,
RefreshCw,
} from "lucide-react";
import ReactMarkdown from "react-markdown";
@@ -23,19 +24,22 @@ import type { DocNavSummary } from "@/hooks/useDocs";
import { DocsOverview } from "./DocsOverview";
import { CodeBlock } from "./CodeBlock";
import { Callout, parseCalloutTag, type CalloutType } from "./Callout";
+import { docSourceUrl, readingMinutes } from "./docsShared";
import { useT, useUiLanguage } from "@/i18n";
import { localeForUiLanguage } from "@/components/runs/format";
import { openExternalUrl } from "@/lib/openExternal";
+import { robustCopy } from "@/lib/clipboard";
interface Props {
slug: string | null;
onSelect: (slug: string) => void;
onShowOverview: () => void;
+ onOpenSearch?: () => void;
}
-export function DocsContent({ slug, onSelect, onShowOverview }: Props) {
+export function DocsContent({ slug, onSelect, onShowOverview, onOpenSearch }: Props) {
if (!slug) {
- return <DocsOverview onSelect={onSelect} />;
+ return <DocsOverview onSelect={onSelect} onOpenSearch={onOpenSearch} />;
}
return (
<DocsContentInner
@@ -46,6 +50,26 @@ export function DocsContent({ slug, onSelect, onShowOverview }: Props) {
);
}
+/*
+ * Reading typography for a guide. The typography plugin's colour variables
+ * are pointed at theme tokens (identical for its normal and inverted
+ * palettes), so one class list reads correctly in light and dark, and the
+ * heading sizes are pinned to the app's own type scale.
+ */
+const ARTICLE_PROSE = [
+ "docs-prose prose max-w-none",
+ "prose-p:text-pretty prose-li:my-1 prose-li:marker:text-foreground-faint",
+ "prose-headings:scroll-mt-8 prose-headings:text-pretty prose-headings:font-semibold prose-headings:text-foreground-strong",
+ "prose-h2:mb-4 prose-h2:mt-12 prose-h2:text-xl",
+ "prose-h3:mb-3 prose-h3:mt-8 prose-h3:text-lg",
+ "prose-h4:text-base",
+ "prose-a:font-normal prose-a:text-accent prose-a:underline prose-a:decoration-accent/30 prose-a:underline-offset-4 hover:prose-a:decoration-accent",
+ "prose-strong:font-semibold prose-strong:text-foreground-strong",
+ "prose-code:rounded-sm prose-code:bg-secondary prose-code:px-1.5 prose-code:py-0.5 prose-code:font-mono prose-code:text-sm prose-code:font-normal prose-code:text-foreground-strong prose-code:before:hidden prose-code:after:hidden",
+ "prose-hr:my-10 prose-hr:border-border",
+ "prose-img:rounded-lg prose-img:border prose-img:border-border",
+].join(" ");
+
function DocsContentInner({
slug,
onSelect,
@@ -84,112 +108,173 @@ function DocsContentInner({
() => formatReviewDate(data?.last_reviewed, uiLanguage),
[data?.last_reviewed, uiLanguage],
);
+ const minutes = useMemo(() => readingMinutes(data?.body ?? ""), [data?.body]);
+ const markdownComponents = useMemo(
+ () => makeMarkdownComponents({ knownSlugs, onInternalNavigate: onSelect }),
+ [knownSlugs, onSelect],
+ );
if (isLoading) {
return <DocPageSkeleton />;
}
if (error || !data) {
return (
- <div className="flex min-h-full items-center justify-center px-8 text-center">
- <div className="max-w-sm rounded-xl border border-destructive/30 bg-destructive/5 p-6">
+ <div className="flex min-h-full items-center justify-center px-8 py-20 text-center">
+ <div className="max-w-sm">
<FileWarning className="mx-auto h-6 w-6 text-destructive" aria-hidden="true" />
- <p className="mt-3 text-sm font-medium text-foreground">
+ <p className="mt-3 text-lg font-semibold text-foreground-strong">
{t("docs.could_not_load")}
</p>
- <button
- type="button"
- onClick={() => void refetch()}
- className="mt-4 inline-flex items-center gap-2 rounded-md border border-border bg-card px-3 py-2 text-xs font-medium transition hover:bg-muted"
- >
- <RefreshCw
- className={
- isFetching
- ? "h-3.5 w-3.5 animate-spin motion-reduce:animate-none"
- : "h-3.5 w-3.5"
- }
- aria-hidden="true"
- />
- {t("docs_overview.retry")}
- </button>
+ <div className="mt-5 flex justify-center gap-2">
+ <button
+ type="button"
+ onClick={() => void refetch()}
+ className="inline-flex h-8 items-center gap-2 rounded-md border border-border-strong px-3 text-sm font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <RefreshCw
+ className={
+ isFetching
+ ? "h-3.5 w-3.5 animate-spin motion-reduce:animate-none"
+ : "h-3.5 w-3.5"
+ }
+ aria-hidden="true"
+ />
+ {t("docs_overview.retry")}
+ </button>
+ <button
+ type="button"
+ onClick={onShowOverview}
+ className="inline-flex h-8 items-center rounded-md px-3 text-sm font-medium text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ {t("docs_sidebar.overview")}
+ </button>
+ </div>
</div>
</div>
);
}
+ const markdownPage = `# ${data.title}\n\n${data.body}`;
+
return (
- <article className="prose prose-neutral dark:prose-invert prose-base mx-auto max-w-3xl px-8 py-10 prose-headings:scroll-mt-20 prose-headings:text-pretty prose-p:text-pretty prose-code:before:hidden prose-code:after:hidden prose-a:text-accent prose-a:no-underline hover:prose-a:underline lg:px-10">
- <header className="not-prose mb-9 border-b border-border pb-6">
- <nav
- aria-label="Breadcrumb"
- className="mb-4 flex items-center gap-1.5 text-xs text-muted-foreground"
- >
+ <article className="mx-auto w-full max-w-reading pb-20 pt-12">
+ <header className="mb-10 border-b border-border pb-8">
+ <nav aria-label="Breadcrumb" className="flex items-center gap-1.5 text-sm">
<button
type="button"
onClick={onShowOverview}
- className="rounded-sm transition-colors hover:text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ className="rounded-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
>
{t("docs_content.breadcrumb")}
</button>
- <ChevronRight className="h-3 w-3" aria-hidden="true" />
- <span className="text-foreground/80" aria-current="page">
+ <span className="text-foreground-faint" aria-hidden="true">/</span>
+ <span className="font-medium text-accent" aria-current="page">
{data.section}
</span>
</nav>
- <h1 className="m-0 text-pretty text-3xl tracking-tight">
+ <h1 className="mt-3 text-pretty font-display text-2xl text-foreground-strong">
{data.title}
</h1>
- <p className="mt-3 max-w-2xl text-pretty text-base leading-7 text-muted-foreground">
- {data.summary}
- </p>
+ {data.summary && (
+ <p className="mt-3 text-pretty text-lg text-muted-foreground">
+ {data.summary}
+ </p>
+ )}
+ <div className="mt-6 flex flex-wrap items-center justify-between gap-3">
+ <p className="flex flex-wrap items-center gap-x-2 text-sm text-muted-foreground">
+ <span>{t("docs_content.reading_time").replace("{0}", String(minutes))}</span>
+ {data.last_reviewed && (
+ <>
+ <span className="text-foreground-faint" aria-hidden="true">·</span>
+ <span>{t("docs_content.reviewed").replace("{0}", reviewedDate)}</span>
+ </>
+ )}
+ </p>
+ <div className="flex items-center gap-1.5">
+ <CopyPageButton markdown={markdownPage} />
+ {data.path && (
+ <a
+ href={docSourceUrl(data.path)}
+ onClick={(event) => {
+ event.preventDefault();
+ void openExternalUrl(docSourceUrl(data.path));
+ }}
+ rel="noopener noreferrer"
+ className="inline-flex h-8 items-center gap-1.5 rounded-md border border-border px-2.5 text-sm font-medium text-muted-foreground transition-colors hover:border-border-strong hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ {t("docs_content.view_source")}
+ <ExternalLink className="h-3 w-3" aria-hidden="true" />
+ </a>
+ )}
+ </div>
+ </div>
</header>
- <ReactMarkdown
- remarkPlugins={[remarkGfm]}
- rehypePlugins={[
- rehypeSlug,
- [rehypeAutolinkHeadings, { behavior: "wrap" }],
- ]}
- components={makeMarkdownComponents({
- knownSlugs,
- onInternalNavigate: onSelect,
- })}
- >
- {data.body}
- </ReactMarkdown>
+ <div className={ARTICLE_PROSE}>
+ <ReactMarkdown
+ remarkPlugins={[remarkGfm]}
+ rehypePlugins={[
+ rehypeSlug,
+ [rehypeAutolinkHeadings, { behavior: "wrap" }],
+ ]}
+ components={markdownComponents}
+ >
+ {data.body}
+ </ReactMarkdown>
+ </div>
{relatedDocs.length > 0 && (
<RelatedGuides docs={relatedDocs} onSelect={onSelect} />
)}
- <footer className="not-prose mt-12 border-t border-border pt-6">
- <div className="mb-4 flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
- <span className="flex items-center gap-1.5">
- <Clock className="h-3 w-3" aria-hidden="true" />
- {data.last_reviewed ? (
- <>{t("docs_content.last_reviewed")} {reviewedDate}</>
- ) : (
- <>{t("docs_content.review_unavailable")}</>
- )}
- </span>
- </div>
-
- <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
- <NavCard
- doc={neighbors.prev}
- direction="prev"
- onSelect={onSelect}
- />
- <NavCard
- doc={neighbors.next}
- direction="next"
- onSelect={onSelect}
- />
- </div>
- </footer>
+ {(neighbors.prev || neighbors.next) && (
+ <nav
+ aria-label={t("docs_content.pagination")}
+ className="mt-14 grid grid-cols-1 gap-3 border-t border-border pt-8 sm:grid-cols-2"
+ >
+ <NavCard doc={neighbors.prev} direction="prev" onSelect={onSelect} />
+ <NavCard doc={neighbors.next} direction="next" onSelect={onSelect} />
+ </nav>
+ )}
</article>
);
}
+function CopyPageButton({ markdown }: { markdown: string }) {
+ const t = useT();
+ const [copied, setCopied] = useState(false);
+ const timer = useRef<number | null>(null);
+ useEffect(
+ () => () => {
+ if (timer.current !== null) window.clearTimeout(timer.current);
+ },
+ [],
+ );
+ return (
+ <button
+ type="button"
+ onClick={() => {
+ void robustCopy(markdown).then((ok) => {
+ if (!ok) return;
+ setCopied(true);
+ if (timer.current !== null) window.clearTimeout(timer.current);
+ timer.current = window.setTimeout(() => setCopied(false), 1500);
+ });
+ }}
+ className="inline-flex h-8 items-center gap-1.5 rounded-md border border-border px-2.5 text-sm font-medium text-muted-foreground transition-colors hover:border-border-strong hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ {copied ? (
+ <Check className="h-3.5 w-3.5 text-success" aria-hidden="true" />
+ ) : (
+ <Copy className="h-3.5 w-3.5" aria-hidden="true" />
+ )}
+ <span aria-live="polite">
+ {copied ? t("docs_content.page_copied") : t("docs_content.copy_page")}
+ </span>
+ </button>
+ );
+}
+
// ----------------------------------------------------------------------
// Prev/next computation + NavCard
// ----------------------------------------------------------------------
@@ -218,22 +303,32 @@ function NavCard({
onSelect: (slug: string) => void;
}) {
const t = useT();
- if (!doc) return <div />;
- const Icon = direction === "prev" ? ChevronLeft : ChevronRight;
- const align = direction === "next" ? "text-right items-end" : "items-start";
+ if (!doc) return <div className="hidden sm:block" />;
+ const next = direction === "next";
return (
<button
type="button"
onClick={() => onSelect(doc.slug)}
- className={`flex flex-col gap-1 rounded-md border border-border bg-card/40 p-3 text-left transition hover:bg-muted/40 ${align}`}
+ className={`group flex flex-col gap-1 rounded-lg border border-border px-5 py-4 transition-colors hover:border-border-strong hover:bg-secondary/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${
+ next ? "items-end text-right sm:col-start-2" : "items-start text-left"
+ }`}
>
- <span className="flex items-center gap-1 text-micro uppercase tracking-wider text-muted-foreground">
- {direction === "prev" ? <Icon className="h-3 w-3" aria-hidden="true" /> : null}
- {direction === "prev" ? t("docs_content.prev") : t("docs_content.next")}
- {direction === "next" ? <Icon className="h-3 w-3" aria-hidden="true" /> : null}
+ <span className="flex items-center gap-1.5 text-sm text-muted-foreground">
+ {!next && (
+ <ArrowLeft
+ className="h-3.5 w-3.5 transition-transform motion-safe:group-hover:-translate-x-0.5"
+ aria-hidden="true"
+ />
+ )}
+ {next ? t("docs_content.next") : t("docs_content.prev")}
+ {next && (
+ <ArrowRight
+ className="h-3.5 w-3.5 transition-transform motion-safe:group-hover:translate-x-0.5"
+ aria-hidden="true"
+ />
+ )}
</span>
- <span className="text-sm font-medium">{doc.title}</span>
- <span className="text-xs leading-5 text-muted-foreground">{doc.summary}</span>
+ <span className="text-lg font-medium text-foreground-strong">{doc.title}</span>
</button>
);
}
@@ -257,26 +352,29 @@ function RelatedGuides({
}) {
const t = useT();
return (
- <section
- className="not-prose mt-12 border-t border-border pt-8"
- aria-labelledby="related-guides-title"
- >
- <div className="mb-4 flex items-center gap-2">
- <Link2 className="h-4 w-4 text-primary" aria-hidden="true" />
- <h2 id="related-guides-title" className="text-lg font-semibold">
- {t("docs_content.related_guides")}
- </h2>
- </div>
- <div className="grid gap-3 sm:grid-cols-2">
+ <section className="mt-14" aria-labelledby="related-guides-title">
+ <h2
+ id="related-guides-title"
+ className="text-sm font-semibold text-foreground-strong"
+ >
+ {t("docs_content.related_guides")}
+ </h2>
+ <div className="mt-3 grid gap-3 sm:grid-cols-2">
{docs.map((doc) => (
<button
key={doc.slug}
type="button"
onClick={() => onSelect(doc.slug)}
- className="rounded-lg border border-border bg-card/30 p-4 text-left transition-colors hover:border-primary/30 hover:bg-card/60"
+ className="group rounded-lg border border-border px-4 py-3.5 text-left transition-colors hover:border-border-strong hover:bg-secondary/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
>
- <span className="text-sm font-semibold text-foreground">{doc.title}</span>
- <span className="mt-1.5 block text-xs leading-5 text-muted-foreground">
+ <span className="flex items-center justify-between gap-3 text-base font-medium text-foreground">
+ {doc.title}
+ <ArrowRight
+ className="h-3.5 w-3.5 shrink-0 text-foreground-faint transition-colors group-hover:text-foreground"
+ aria-hidden="true"
+ />
+ </span>
+ <span className="mt-1 line-clamp-2 text-sm text-muted-foreground">
{doc.summary}
</span>
</button>
@@ -289,29 +387,24 @@ function RelatedGuides({
function DocPageSkeleton() {
const t = useT();
return (
- <div className="mx-auto min-h-full w-full max-w-3xl px-8 py-10" role="status">
- <div className="flex items-center gap-2 text-xs text-muted-foreground">
- <RefreshCw
- className="h-3.5 w-3.5 animate-spin text-primary motion-reduce:animate-none"
- aria-hidden="true"
- />
- {t("docs_overview.loading_page")}
- </div>
- <div className="mt-6 animate-pulse motion-reduce:animate-none">
- <div className="h-3 w-24 rounded-full bg-muted" />
- <div className="mt-4 h-8 w-3/5 rounded-md bg-muted" />
- <div className="mt-4 h-px bg-border" />
- <div className="mt-8 space-y-3">
- <div className="h-3 w-full rounded-full bg-muted/80" />
- <div className="h-3 w-11/12 rounded-full bg-muted/80" />
- <div className="h-3 w-4/5 rounded-full bg-muted/80" />
+ <div className="mx-auto w-full max-w-reading pb-20 pt-12" role="status">
+ <span className="sr-only">{t("docs_overview.loading_page")}</span>
+ <div className="animate-pulse motion-reduce:animate-none" aria-hidden="true">
+ <div className="h-3 w-40 rounded-full bg-muted" />
+ <div className="mt-5 h-7 w-3/5 rounded-md bg-muted" />
+ <div className="mt-4 h-3.5 w-4/5 rounded-full bg-muted/70" />
+ <div className="mt-8 h-px bg-border" />
+ <div className="mt-10 space-y-3.5">
+ <div className="h-3 w-full rounded-full bg-muted/70" />
+ <div className="h-3 w-11/12 rounded-full bg-muted/70" />
+ <div className="h-3 w-4/5 rounded-full bg-muted/70" />
</div>
- <div className="mt-10 h-5 w-2/5 rounded-full bg-muted" />
- <div className="mt-5 space-y-3">
- <div className="h-3 w-full rounded-full bg-muted/80" />
- <div className="h-3 w-5/6 rounded-full bg-muted/80" />
- <div className="h-28 rounded-lg border border-border bg-card/40" />
+ <div className="mt-12 h-4 w-2/5 rounded-full bg-muted" />
+ <div className="mt-5 space-y-3.5">
+ <div className="h-3 w-full rounded-full bg-muted/70" />
+ <div className="h-3 w-5/6 rounded-full bg-muted/70" />
</div>
+ <div className="mt-6 h-28 rounded-lg border border-border bg-card" />
</div>
</div>
);
@@ -400,7 +493,7 @@ function makeMarkdownComponents(ctx: MarkdownContext): Components {
return <Callout type={tagged.type}>{tagged.children}</Callout>;
}
return (
- <blockquote className="border-l-2 border-border pl-4 italic text-muted-foreground">
+ <blockquote className="border-l-2 border-border-strong pl-4 not-italic text-foreground-secondary [&_p:before]:content-none [&_p:after]:content-none">
{children}
</blockquote>
);
@@ -447,14 +540,38 @@ function makeMarkdownComponents(ctx: MarkdownContext): Components {
);
},
- // Tables with a bit more padding for better readability.
+ // Tables sit in their own framed, horizontally scrollable box; cells are
+ // styled here because the frame opts out of the prose rules.
table({ children }) {
return (
- <div className="not-prose my-4 overflow-x-auto rounded-md border border-border">
- <table className="w-full text-sm">{children}</table>
+ <div className="not-prose my-6 overflow-x-auto rounded-lg border border-border">
+ <table className="w-full border-collapse text-left text-base">{children}</table>
</div>
);
},
+ thead({ children }) {
+ return <thead className="bg-secondary/50">{children}</thead>;
+ },
+ th({ children, style }) {
+ return (
+ <th
+ style={style}
+ className="border-b border-border px-4 py-2.5 text-sm font-semibold text-foreground-strong"
+ >
+ {children}
+ </th>
+ );
+ },
+ td({ children, style }) {
+ return (
+ <td
+ style={style}
+ className="border-t border-border px-4 py-2.5 align-top text-foreground-secondary first:font-medium first:text-foreground [&_code]:rounded-sm [&_code]:bg-secondary [&_code]:px-1 [&_code]:font-mono [&_code]:text-sm"
+ >
+ {children}
+ </td>
+ );
+ },
};
}
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsx
index 2c44705d1e..cfaf1c7628 100644
--- a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsx
@@ -32,24 +32,26 @@ describe("DocsOverview", () => {
expect(screen.getByRole("status")).toBeTruthy();
});
- it("renders local quick links and opens the redesigned online docs", async () => {
+ it("draws the first topic as a reading path and the rest as topic cards", async () => {
+ const doc = (slug: string, title: string, section: string, order: number) => ({
+ title,
+ slug,
+ diataxis: "howto",
+ summary: `About ${title}.`,
+ section,
+ section_order: order,
+ order: 1,
+ tags: [],
+ related: [],
+ });
vi.stubGlobal(
"fetch",
vi.fn(async () =>
new Response(
JSON.stringify({
- unclassified: [
- {
- title: "Architecture overview",
- slug: "architecture-overview",
- diataxis: "unclassified",
- summary: "See how the main parts work together.",
- section: "Reference",
- section_order: 7,
- order: 1,
- tags: [],
- related: [],
- },
+ howto: [
+ doc("welcome", "Welcome", "Start here", 1),
+ doc("architecture-overview", "Architecture overview", "Reference", 7),
],
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
@@ -59,17 +61,25 @@ describe("DocsOverview", () => {
const openSpy = vi
.spyOn(openExternal, "openExternalUrl")
.mockResolvedValue(true);
-
- renderOverview();
+ const selected: string[] = [];
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false, gcTime: 0 } },
+ });
+ render(
+ <QueryClientProvider client={client}>
+ <DocsOverview onSelect={(slug) => selected.push(slug)} />
+ </QueryClientProvider>,
+ );
await waitFor(() => {
- expect(screen.getByText("Architecture overview")).toBeTruthy();
- expect(screen.getByText("Browse by Topic")).toBeTruthy();
+ expect(screen.getByText("Get started")).toBeTruthy();
+ expect(screen.getByText("Browse by topic")).toBeTruthy();
});
- fireEvent.click(
- screen.getByRole("link", { name: /open redesigned online docs/i }),
- );
+ expect(screen.getByText("Welcome")).toBeTruthy();
+ fireEvent.click(screen.getByRole("button", { name: /Architecture overview/ }));
+ expect(selected).toEqual(["architecture-overview"]);
+ fireEvent.click(screen.getByRole("link", { name: /view on github/i }));
expect(openSpy).toHaveBeenCalledWith("https://github.com/PersonalJarvis/PersonalJarvis/tree/main/docs");
});
});
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsx
index a2afcd89d9..0dd61705bd 100644
--- a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsx
@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
import {
ArrowRight,
BookOpen,
@@ -6,6 +6,7 @@ import {
FileWarning,
Loader2,
RefreshCw,
+ Search,
} from "lucide-react";
import {
@@ -14,86 +15,93 @@ import {
type DocSection,
type DocNavSummary,
} from "@/hooks/useDocs";
+import { useRecentDocs } from "@/hooks/useRecentDocs";
import { useT } from "@/i18n";
import { openExternalUrl } from "@/lib/openExternal";
+import { cn } from "@/lib/utils";
+import { ONLINE_DOCS_URL, SearchTrigger, sectionIcon } from "./docsShared";
+
+/** Links a topic card shows before it offers "Show all". */
+const TOPIC_PREVIEW_COUNT = 4;
-const ONLINE_DOCS_URL = "https://github.com/PersonalJarvis/PersonalJarvis/tree/main/docs";
interface Props {
onSelect: (slug: string) => void;
+ onOpenSearch?: () => void;
}
-export function DocsOverview({ onSelect }: Props) {
+/**
+ * The docs home: a title with the search field, the first topic as a
+ * numbered reading path, recently opened guides, and every other topic as a
+ * card listing its guides.
+ */
+export function DocsOverview({ onSelect, onOpenSearch }: Props) {
const t = useT();
const { data, isLoading, isFetching, error, refetch } = useDocsGrouped();
+ const { recent } = useRecentDocs();
const sections = useMemo(() => buildDocSections(data), [data]);
- const allDocs = useMemo(
- () => sections.flatMap((section) => section.docs),
- [sections],
- );
- const featured = allDocs.slice(0, 4);
+ const sectionBySlug = useMemo(() => {
+ const map = new Map<string, string>();
+ for (const section of sections) {
+ for (const doc of section.docs) map.set(doc.slug, section.name);
+ }
+ return map;
+ }, [sections]);
+ const [startSection, ...topics] = sections;
+ const recentDocs = recent.filter((doc) => sectionBySlug.has(doc.slug)).slice(0, 3);
return (
- <section className="mx-auto min-h-full w-full max-w-5xl px-8 py-8 lg:px-12">
- <div className="border-b border-border pb-8">
- <div className="mb-3 flex items-center gap-2 text-sm font-medium text-muted-foreground">
- <BookOpen className="h-4 w-4" aria-hidden="true" />
+ <div className="mx-auto w-full max-w-page pb-20 pt-14">
+ <header className="max-w-reading">
+ <p className="text-sm font-medium text-accent">
{t("docs_overview.eyebrow")}
- </div>
- <h1 className="text-2xl font-semibold text-foreground-strong">
+ </p>
+ <h1 className="mt-3 font-display text-2xl text-foreground-strong">
{t("docs_overview.title")}
</h1>
- <p className="mt-2 max-w-2xl text-base text-muted-foreground">
+ <p className="mt-4 text-lg text-muted-foreground">
{t("docs_overview.description")}
</p>
- <a
- href={ONLINE_DOCS_URL}
- onClick={(event) => {
- event.preventDefault();
- void openExternalUrl(ONLINE_DOCS_URL);
- }}
- rel="noopener noreferrer"
- className="mt-5 inline-flex h-9 items-center gap-2 rounded-md border border-border-strong px-4 text-base font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
- >
- {t("docs_overview.online_docs")}
- <ExternalLink className="h-3.5 w-3.5" aria-hidden="true" />
- </a>
- </div>
+ {onOpenSearch && (
+ <SearchTrigger
+ size="lg"
+ onClick={onOpenSearch}
+ className="mt-8 max-w-xl"
+ />
+ )}
+ </header>
{isLoading ? (
<OverviewSkeleton />
) : error ? (
- <div className="mt-8 rounded-lg border border-destructive/20 bg-destructive/[0.08] p-5">
- <div className="flex items-start gap-3">
- <FileWarning className="mt-0.5 h-5 w-5 text-destructive" aria-hidden="true" />
- <div>
- <h2 className="text-lg font-semibold text-foreground-strong">
- {t("docs_overview.load_failed_title")}
- </h2>
- <p className="mt-1 text-base text-muted-foreground">
- {t("docs_overview.load_failed_description")}
- </p>
- <button
- type="button"
- onClick={() => void refetch()}
- className="mt-4 inline-flex items-center gap-2 rounded-md border border-border bg-card px-3 py-2 text-xs font-medium transition hover:bg-muted"
- >
- <RefreshCw
- className={
- isFetching
- ? "h-3.5 w-3.5 animate-spin motion-reduce:animate-none"
- : "h-3.5 w-3.5"
- }
- aria-hidden="true"
- />
- {t("docs_overview.retry")}
- </button>
- </div>
+ <div className="mt-12 flex items-start gap-3 rounded-lg border border-destructive/30 bg-destructive/[0.06] p-5">
+ <FileWarning className="mt-0.5 h-5 w-5 shrink-0 text-destructive" aria-hidden="true" />
+ <div>
+ <h2 className="text-lg font-semibold text-foreground-strong">
+ {t("docs_overview.load_failed_title")}
+ </h2>
+ <p className="mt-1 text-base text-muted-foreground">
+ {t("docs_overview.load_failed_description")}
+ </p>
+ <button
+ type="button"
+ onClick={() => void refetch()}
+ className="mt-4 inline-flex h-8 items-center gap-2 rounded-md border border-border-strong px-3 text-sm font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <RefreshCw
+ className={cn(
+ "h-3.5 w-3.5",
+ isFetching && "animate-spin motion-reduce:animate-none",
+ )}
+ aria-hidden="true"
+ />
+ {t("docs_overview.retry")}
+ </button>
</div>
</div>
- ) : featured.length === 0 ? (
- <div className="mt-8 rounded-lg border border-border bg-card p-8 text-center">
- <BookOpen className="mx-auto h-8 w-8 text-muted-foreground/50" aria-hidden="true" />
+ ) : !startSection ? (
+ <div className="mt-12 rounded-lg border border-border p-10 text-center">
+ <BookOpen className="mx-auto h-6 w-6 text-foreground-faint" aria-hidden="true" />
<h2 className="mt-3 text-lg font-semibold text-foreground-strong">
{t("docs_overview.empty_title")}
</h2>
@@ -102,74 +110,170 @@ export function DocsOverview({ onSelect }: Props) {
</p>
</div>
) : (
- <div className="mt-10">
- <div className="mb-5 flex items-end justify-between gap-4">
+ <>
+ <StartPath section={startSection} onSelect={onSelect} />
+
+ {recentDocs.length > 0 && (
+ <section className="mt-14" aria-labelledby="docs-recent-title">
+ <h2
+ id="docs-recent-title"
+ className="text-sm font-semibold text-foreground-strong"
+ >
+ {t("docs_overview.recent_title")}
+ </h2>
+ <div className="mt-3 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+ {recentDocs.map((doc) => (
+ <button
+ key={doc.slug}
+ type="button"
+ onClick={() => onSelect(doc.slug)}
+ className="group flex items-center justify-between gap-3 rounded-md border border-border px-4 py-3 text-left transition-colors hover:border-border-strong hover:bg-secondary/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <span className="min-w-0">
+ <span className="block truncate text-base font-medium text-foreground">
+ {doc.title}
+ </span>
+ <span className="mt-0.5 block truncate text-sm text-muted-foreground">
+ {sectionBySlug.get(doc.slug)}
+ </span>
+ </span>
+ <ArrowRight
+ className="h-3.5 w-3.5 shrink-0 text-foreground-faint transition-colors group-hover:text-foreground"
+ aria-hidden="true"
+ />
+ </button>
+ ))}
+ </div>
+ </section>
+ )}
+
+ {topics.length > 0 && (
+ <section className="mt-16" aria-labelledby="docs-topics-title">
+ <h2
+ id="docs-topics-title"
+ className="text-xl font-semibold text-foreground-strong"
+ >
+ {t("docs_overview.browse_by_topic")}
+ </h2>
+ <p className="mt-1.5 text-base text-muted-foreground">
+ {t("docs_overview.browse_description")}
+ </p>
+ <div className="mt-6 grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+ {topics.map((section) => (
+ <TopicCard key={section.name} section={section} onSelect={onSelect} />
+ ))}
+ </div>
+ </section>
+ )}
+
+ <section className="mt-16 flex flex-col gap-5 border-t border-border pt-8 md:flex-row md:items-center md:justify-between">
<div>
<h2 className="text-lg font-semibold text-foreground-strong">
- {t("docs_overview.local_library")}
+ {t("docs_overview.help_title")}
</h2>
<p className="mt-1 text-base text-muted-foreground">
- {t("docs_overview.local_library_description")}
+ {t("docs_overview.help_description")}
</p>
</div>
- <span className="shrink-0 text-sm text-foreground-faint">
- {allDocs.length} {t("docs_sidebar.documents")}
- </span>
- </div>
-
- <div className="grid gap-4 sm:grid-cols-2">
- {featured.map((doc) => (
- <DocCard key={doc.slug} doc={doc} onSelect={onSelect} />
- ))}
- </div>
-
- <div className="mt-12 border-t border-border pt-8">
- <h2 className="text-lg font-semibold text-foreground-strong">
- {t("docs_overview.browse_by_topic")}
- </h2>
- <p className="mt-1 text-base text-muted-foreground">
- {t("docs_overview.browse_description")}
- </p>
- <div className="mt-5 grid gap-4 md:grid-cols-2 xl:grid-cols-3">
- {sections.map((section) => (
- <SectionCard key={section.name} section={section} onSelect={onSelect} />
- ))}
+ <div className="flex shrink-0 flex-wrap gap-2">
+ {onOpenSearch && (
+ <button
+ type="button"
+ onClick={onOpenSearch}
+ className="inline-flex h-9 items-center gap-2 rounded-md border border-border-strong px-4 text-base font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <Search className="h-3.5 w-3.5" aria-hidden="true" />
+ {t("docs.search_button")}
+ </button>
+ )}
+ <a
+ href={ONLINE_DOCS_URL}
+ onClick={(event) => {
+ event.preventDefault();
+ void openExternalUrl(ONLINE_DOCS_URL);
+ }}
+ rel="noopener noreferrer"
+ className="inline-flex h-9 items-center gap-2 rounded-md border border-border-strong px-4 text-base font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ {t("docs_overview.online_docs")}
+ <ExternalLink className="h-3.5 w-3.5" aria-hidden="true" />
+ </a>
</div>
- </div>
- </div>
+ </section>
+ </>
)}
- </section>
+ </div>
);
}
-function DocCard({
- doc,
+/** The first topic, drawn as an ordered reading path. */
+function StartPath({
+ section,
onSelect,
}: {
- doc: DocNavSummary;
+ section: DocSection;
onSelect: (slug: string) => void;
}) {
+ const t = useT();
+ const Icon = sectionIcon(section.name);
+ const first = section.docs[0];
return (
- <button
- type="button"
- onClick={() => onSelect(doc.slug)}
- className="group flex min-h-36 flex-col rounded-lg border border-border bg-card p-5 text-left transition-colors hover:border-border-strong focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+ <section
+ className="mt-14 grid overflow-hidden rounded-lg border border-border bg-card lg:grid-cols-5"
+ aria-labelledby="docs-start-title"
>
- <span className="text-xs font-medium uppercase tracking-wide text-foreground-faint">
- {doc.section}
- </span>
- <span className="mt-2 flex items-center gap-2 text-lg font-semibold text-foreground-strong">
- {doc.title}
- <ArrowRight className="h-4 w-4 text-muted-foreground transition motion-safe:group-hover:translate-x-0.5" aria-hidden="true" />
- </span>
- <span className="mt-2 text-base text-muted-foreground">
- {doc.summary}
- </span>
- </button>
+ <div className="flex flex-col border-b border-border p-7 lg:col-span-2 lg:border-b-0 lg:border-r">
+ <span className="flex h-9 w-9 items-center justify-center rounded-md bg-accent-soft text-accent">
+ <Icon className="h-4 w-4" aria-hidden="true" />
+ </span>
+ <h2
+ id="docs-start-title"
+ className="mt-5 text-xl font-semibold text-foreground-strong"
+ >
+ {t("docs_overview.start_title")}
+ </h2>
+ <p className="mt-2 text-base text-muted-foreground">
+ {t("docs_overview.start_description")}
+ </p>
+ {first && (
+ <button
+ type="button"
+ onClick={() => onSelect(first.slug)}
+ className="mt-6 inline-flex h-9 w-fit items-center gap-2 rounded-md bg-primary px-4 text-base font-medium text-primary-foreground transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card"
+ >
+ {t("docs_overview.start_reading")}
+ <ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />
+ </button>
+ )}
+ </div>
+ <ol className="p-3 lg:col-span-3">
+ {section.docs.map((doc, index) => (
+ <li key={doc.slug}>
+ <button
+ type="button"
+ onClick={() => onSelect(doc.slug)}
+ className="group flex w-full items-start gap-4 rounded-md px-4 py-3 text-left transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <span className="mt-px flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-border-strong text-xs font-medium tabular-nums text-muted-foreground transition-colors group-hover:border-accent group-hover:text-accent">
+ {index + 1}
+ </span>
+ <span className="min-w-0">
+ <span className="block text-base font-medium text-foreground">
+ {doc.title}
+ </span>
+ <span className="mt-0.5 line-clamp-1 text-sm text-muted-foreground">
+ {doc.summary}
+ </span>
+ </span>
+ </button>
+ </li>
+ ))}
+ </ol>
+ </section>
);
}
-function SectionCard({
+function TopicCard({
section,
onSelect,
}: {
@@ -177,55 +281,82 @@ function SectionCard({
onSelect: (slug: string) => void;
}) {
const t = useT();
- const first = section.docs[0];
+ const [expanded, setExpanded] = useState(false);
+ const Icon = sectionIcon(section.name);
+ const visible: DocNavSummary[] = expanded
+ ? section.docs
+ : section.docs.slice(0, TOPIC_PREVIEW_COUNT);
+ const hidden = section.docs.length - TOPIC_PREVIEW_COUNT;
return (
- <button
- type="button"
- onClick={() => onSelect(first.slug)}
- className="group rounded-lg border border-border bg-card p-5 text-left transition-colors hover:border-border-strong focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
- >
- <span className="flex items-center justify-between gap-3 text-lg font-semibold text-foreground-strong">
- {section.name}
- <ArrowRight className="h-4 w-4 text-muted-foreground transition-transform motion-safe:group-hover:translate-x-0.5" aria-hidden="true" />
- </span>
- <span className="mt-2 block text-base text-muted-foreground">
- {first.summary}
- </span>
- <span className="mt-3 block text-sm text-foreground-faint">
- {section.docs.length}{" "}
- {section.docs.length === 1
- ? t("docs_overview.guide")
- : t("docs_overview.guides")}
- </span>
- </button>
+ <section className="flex flex-col rounded-lg border border-border bg-card p-5">
+ <div className="flex items-center gap-3">
+ <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md bg-secondary text-foreground-secondary">
+ <Icon className="h-4 w-4" aria-hidden="true" />
+ </span>
+ <h3 className="text-lg font-semibold text-foreground-strong">
+ {section.name}
+ </h3>
+ </div>
+ <ul className="mt-4 flex-1 space-y-px">
+ {visible.map((doc) => (
+ <li key={doc.slug}>
+ <button
+ type="button"
+ onClick={() => onSelect(doc.slug)}
+ title={doc.summary}
+ className="group flex w-full items-center justify-between gap-3 rounded-sm py-1.5 text-left text-base text-foreground-secondary transition-colors hover:text-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <span className="min-w-0 truncate">{doc.title}</span>
+ <ArrowRight
+ className="h-3.5 w-3.5 shrink-0 opacity-0 transition-opacity group-hover:opacity-100"
+ aria-hidden="true"
+ />
+ </button>
+ </li>
+ ))}
+ </ul>
+ {hidden > 0 && (
+ <button
+ type="button"
+ onClick={() => setExpanded((value) => !value)}
+ aria-expanded={expanded}
+ className="mt-3 w-fit rounded-sm text-sm font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ {expanded
+ ? t("docs_overview.show_less")
+ : t("docs_overview.show_all").replace("{0}", String(section.docs.length))}
+ </button>
+ )}
+ </section>
);
}
function OverviewSkeleton() {
const t = useT();
return (
- <div className="mt-8" role="status" aria-live="polite">
- <div className="flex items-start gap-3 rounded-lg border border-accent/20 bg-accent-soft p-4">
+ <div className="mt-14" role="status" aria-live="polite">
+ <div className="flex items-center gap-2 text-sm text-muted-foreground">
<Loader2
- className="mt-0.5 h-4 w-4 animate-spin text-primary motion-reduce:animate-none"
+ className="h-3.5 w-3.5 animate-spin text-accent motion-reduce:animate-none"
aria-hidden="true"
/>
- <div>
- <p className="text-base font-medium">{t("docs_overview.indexing_title")}</p>
- <p className="mt-1 text-base text-muted-foreground">
- {t("docs_overview.indexing_description")}
- </p>
- </div>
+ <span className="font-medium text-foreground">
+ {t("docs_overview.indexing_title")}
+ </span>
+ <span className="hidden sm:inline">— {t("docs_overview.indexing_description")}</span>
</div>
- <div className="mt-8 animate-pulse motion-reduce:animate-none">
- <div className="h-4 w-36 rounded-full bg-muted" />
- <div className="mt-2 h-3 w-72 max-w-full rounded-full bg-muted/70" />
- <div className="mt-5 grid gap-3 sm:grid-cols-2">
- {[0, 1, 2, 3].map((item) => (
- <div key={item} className="h-28 rounded-xl border border-border bg-card/30 p-5">
- <div className="h-2 w-20 rounded-full bg-muted" />
- <div className="mt-4 h-3 w-3/5 rounded-full bg-muted" />
- <div className="mt-5 h-2 w-2/5 rounded-full bg-muted/60" />
+ <div className="mt-6 animate-pulse motion-reduce:animate-none" aria-hidden="true">
+ <div className="h-56 rounded-lg border border-border bg-card" />
+ <div className="mt-14 h-4 w-40 rounded-full bg-muted" />
+ <div className="mt-6 grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+ {[0, 1, 2].map((item) => (
+ <div key={item} className="h-48 rounded-lg border border-border bg-card p-5">
+ <div className="h-3 w-1/2 rounded-full bg-muted" />
+ <div className="mt-6 space-y-3">
+ <div className="h-2.5 w-4/5 rounded-full bg-muted/70" />
+ <div className="h-2.5 w-3/5 rounded-full bg-muted/70" />
+ <div className="h-2.5 w-2/3 rounded-full bg-muted/70" />
+ </div>
</div>
))}
</div>
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsx
index 5021a429e5..c1f8e26404 100644
--- a/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsx
@@ -1,9 +1,17 @@
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
import * as Dialog from "@radix-ui/react-dialog";
import { Command } from "cmdk";
-import { FileText, FileWarning, RefreshCw, Search } from "lucide-react";
+import {
+ Clock,
+ FileText,
+ FileWarning,
+ Loader2,
+ RefreshCw,
+ Search,
+} from "lucide-react";
-import { useDocSearch } from "@/hooks/useDocs";
+import { buildDocSections, useDocSearch, useDocsGrouped } from "@/hooks/useDocs";
+import { useRecentDocs } from "@/hooks/useRecentDocs";
import { cn } from "@/lib/utils";
import { useT } from "@/i18n";
@@ -35,24 +43,55 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {
undefined,
open,
);
+ const grouped = useDocsGrouped();
+ const { recent } = useRecentDocs();
+
+ // With nothing typed yet the dialog offers a starting point: the guides
+ // opened most recently, then the first topic's reading path.
+ const suggestions = useMemo(() => {
+ const sections = buildDocSections(grouped.data);
+ const known = new Map<string, { title: string; section: string }>();
+ for (const section of sections) {
+ for (const doc of section.docs) {
+ known.set(doc.slug, { title: doc.title, section: section.name });
+ }
+ }
+ const recentRows: SuggestionRow[] = [];
+ for (const doc of recent) {
+ const entry = known.get(doc.slug);
+ if (entry) recentRows.push({ slug: doc.slug, ...entry });
+ }
+ const start = sections[0];
+ const startRows: SuggestionRow[] = (start?.docs ?? [])
+ .filter((doc) => !recentRows.some((row) => row.slug === doc.slug))
+ .map((doc) => ({ slug: doc.slug, title: doc.title, section: start.name }));
+ return { recentRows, startName: start?.name ?? "", startRows };
+ }, [grouped.data, recent]);
// Reset the query on close so a re-open starts fresh.
useEffect(() => {
if (!open) setQuery("");
}, [open]);
+ const choose = (slug: string) => {
+ onSelect(slug);
+ onOpenChange(false);
+ };
+
+ const hasSuggestions =
+ suggestions.recentRows.length + suggestions.startRows.length > 0;
+
return (
<Dialog.Root open={open} onOpenChange={onOpenChange}>
<Dialog.Portal>
<Dialog.Overlay className="fixed inset-0 z-40 bg-scrim/60 backdrop-blur-sm data-[state=open]:animate-in data-[state=open]:fade-in-0 motion-reduce:animate-none" />
- <Dialog.Content className="fixed left-1/2 top-[15%] z-50 w-[min(640px,calc(100vw-2rem))] -translate-x-1/2 overflow-hidden rounded-lg bg-popover shadow-float data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 motion-reduce:animate-none">
+ <Dialog.Content className="fixed left-1/2 top-[12%] z-50 w-[min(680px,calc(100vw-2rem))] -translate-x-1/2 overflow-hidden rounded-lg bg-popover shadow-float data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 motion-reduce:animate-none">
<Dialog.Title className="sr-only">{t("docs.search_modal_title")}</Dialog.Title>
<Dialog.Description className="sr-only">
{t("docs.search_hint")}
</Dialog.Description>
<Command shouldFilter={false} loop>
- {/* Header / Input */}
- <div className="flex items-center gap-2 border-b border-border px-3 py-2">
+ <div className="flex h-14 items-center gap-3 border-b border-border px-4">
<Search className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden="true" />
<Command.Input
value={query}
@@ -62,26 +101,62 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {
name="docs-search"
autoComplete="off"
autoFocus
- className="flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+ className="h-full flex-1 bg-transparent text-lg text-foreground outline-none placeholder:text-foreground-faint"
/>
- <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 text-micro font-medium text-muted-foreground">
+ {isFetching && debouncedQuery.trim() && (
+ <Loader2
+ className="h-4 w-4 shrink-0 animate-spin text-muted-foreground motion-reduce:animate-none"
+ aria-hidden="true"
+ />
+ )}
+ <kbd className="shrink-0 rounded-sm border border-border px-1.5 py-0.5 font-sans text-xs font-medium text-muted-foreground">
Esc
</kbd>
</div>
- {/* Results */}
- <Command.List className="max-h-80 overflow-y-auto p-1">
+ <Command.List className="max-h-96 overflow-y-auto p-2">
{!debouncedQuery.trim() ? (
- <div className="px-3 py-6 text-center text-xs text-muted-foreground">
- {t("docs.search_hint")}
- </div>
- ) : isFetching ? (
- <div className="px-3 py-6 text-center text-xs text-muted-foreground">
+ !hasSuggestions ? (
+ <div className="px-3 py-10 text-center text-base text-muted-foreground">
+ {t("docs.search_hint")}
+ </div>
+ ) : (
+ <>
+ {suggestions.recentRows.length > 0 && (
+ <Command.Group heading={t("docs.recent")} className={GROUP_CLASS}>
+ {suggestions.recentRows.map((row) => (
+ <SuggestionItem
+ key={`recent-${row.slug}`}
+ value={`recent-${row.slug}`}
+ icon={Clock}
+ row={row}
+ onSelect={() => choose(row.slug)}
+ />
+ ))}
+ </Command.Group>
+ )}
+ {suggestions.startRows.length > 0 && (
+ <Command.Group heading={suggestions.startName} className={GROUP_CLASS}>
+ {suggestions.startRows.map((row) => (
+ <SuggestionItem
+ key={`start-${row.slug}`}
+ value={`start-${row.slug}`}
+ icon={FileText}
+ row={row}
+ onSelect={() => choose(row.slug)}
+ />
+ ))}
+ </Command.Group>
+ )}
+ </>
+ )
+ ) : isFetching && results.length === 0 ? (
+ <div className="px-3 py-10 text-center text-base text-muted-foreground">
{t("docs.search_loading")}
</div>
) : error ? (
<div
- className="flex flex-col items-center px-3 py-6 text-center text-xs text-muted-foreground"
+ className="flex flex-col items-center px-3 py-10 text-center text-base text-muted-foreground"
role="alert"
>
<FileWarning
@@ -92,14 +167,14 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {
<button
type="button"
onClick={() => void refetch()}
- className="mt-3 inline-flex items-center gap-1.5 rounded-md border border-border bg-card px-3 py-1.5 font-medium text-foreground transition-colors hover:bg-muted"
+ className="mt-3 inline-flex h-8 items-center gap-1.5 rounded-md border border-border-strong px-3 text-sm font-medium text-foreground transition-colors hover:bg-secondary"
>
<RefreshCw className="h-3 w-3" aria-hidden="true" />
{t("docs.search_retry")}
</button>
</div>
) : results.length === 0 ? (
- <Command.Empty className="px-3 py-6 text-center text-xs text-muted-foreground">
+ <Command.Empty className="px-3 py-10 text-center text-base text-muted-foreground">
{t("docs.no_results").replace("{0}", debouncedQuery)}
</Command.Empty>
) : (
@@ -107,40 +182,42 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {
<Command.Item
key={r.slug}
value={r.slug}
- onSelect={() => {
- onSelect(r.slug);
- onOpenChange(false);
- }}
+ onSelect={() => choose(r.slug)}
className={cn(
- "flex cursor-pointer flex-col gap-1 rounded-md px-3 py-2 text-sm",
- "data-[selected=true]:bg-muted",
+ "group flex cursor-pointer gap-3 rounded-md px-3 py-2.5",
+ "data-[selected=true]:bg-secondary",
)}
>
- <div className="flex items-center gap-2">
- <FileText className="h-3 w-3 shrink-0 text-muted-foreground" aria-hidden="true" />
- <span className="flex-1 truncate font-medium">
- {r.title}
- </span>
- <span className="shrink-0 text-micro uppercase tracking-wider text-muted-foreground">
- {r.section}
- </span>
- </div>
- <div className="ml-5 line-clamp-2 text-xs text-muted-foreground [&>mark]:bg-foreground/30 [&>mark]:text-foreground">
- {renderSearchSnippet(r.snippet)}
+ <FileText
+ className="mt-0.5 h-4 w-4 shrink-0 text-foreground-faint group-data-[selected=true]:text-accent"
+ aria-hidden="true"
+ />
+ <div className="min-w-0 flex-1">
+ <div className="flex items-baseline justify-between gap-3">
+ <span className="truncate text-base font-medium text-foreground-strong">
+ {r.title}
+ </span>
+ <span className="shrink-0 text-xs text-muted-foreground">
+ {r.section}
+ </span>
+ </div>
+ <div className="mt-0.5 line-clamp-2 text-sm text-muted-foreground [&>mark]:rounded-sm [&>mark]:bg-accent-soft [&>mark]:px-0.5 [&>mark]:text-foreground-strong">
+ {renderSearchSnippet(r.snippet)}
+ </div>
</div>
</Command.Item>
))
)}
</Command.List>
- {/* Footer */}
- <div className="flex items-center justify-between border-t border-border bg-muted/20 px-3 py-1.5 text-micro text-muted-foreground">
- <span>
- <kbd className="rounded border border-border px-1 font-medium">↑↓</kbd>{" "}
+ <div className="flex items-center gap-4 border-t border-border px-4 py-2 text-xs text-muted-foreground">
+ <span className="flex items-center gap-1.5">
+ <kbd className={KBD_CLASS}>↑</kbd>
+ <kbd className={KBD_CLASS}>↓</kbd>
{t("docs_search_modal.navigate")}
</span>
- <span>
- <kbd className="rounded border border-border px-1 font-medium">↵</kbd>{" "}
+ <span className="flex items-center gap-1.5">
+ <kbd className={KBD_CLASS}>↵</kbd>
{t("docs_search_modal.open")}
</span>
</div>
@@ -151,6 +228,45 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {
);
}
+interface SuggestionRow {
+ slug: string;
+ title: string;
+ section: string;
+}
+
+const GROUP_CLASS =
+ "[&_[cmdk-group-heading]]:px-3 [&_[cmdk-group-heading]]:pb-1.5 [&_[cmdk-group-heading]]:pt-3 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground";
+
+const KBD_CLASS =
+ "inline-flex h-5 min-w-5 items-center justify-center rounded-sm border border-border px-1 font-sans text-xs font-medium";
+
+function SuggestionItem({
+ value,
+ icon: Icon,
+ row,
+ onSelect,
+}: {
+ value: string;
+ icon: typeof FileText;
+ row: SuggestionRow;
+ onSelect: () => void;
+}) {
+ return (
+ <Command.Item
+ value={value}
+ onSelect={onSelect}
+ className="group flex cursor-pointer items-center gap-3 rounded-md px-3 py-2 data-[selected=true]:bg-secondary"
+ >
+ <Icon
+ className="h-4 w-4 shrink-0 text-foreground-faint group-data-[selected=true]:text-accent"
+ aria-hidden="true"
+ />
+ <span className="min-w-0 flex-1 truncate text-base text-foreground">{row.title}</span>
+ <span className="shrink-0 text-xs text-muted-foreground">{row.section}</span>
+ </Command.Item>
+ );
+}
+
export function renderSearchSnippet(value: string): React.ReactNode {
const parts = value.split(/(<mark>|<\/mark>)/gi);
let marked = false;
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsx
index efe39e3f61..cabd93c872 100644
--- a/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsx
@@ -1,23 +1,12 @@
-import { useMemo, useState } from "react";
-import {
- ChevronDown,
- ChevronRight,
- Clock,
- FileText,
- Loader2,
- RefreshCw,
- Search,
-} from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { ChevronDown, ExternalLink, RefreshCw } from "lucide-react";
import { ScrollArea } from "@/components/ui/scroll-area";
import { cn } from "@/lib/utils";
-import {
- buildDocSections,
- useDocsGrouped,
- type DocNavSummary,
-} from "@/hooks/useDocs";
-import { useRecentDocs } from "@/hooks/useRecentDocs";
+import { buildDocSections, useDocsGrouped } from "@/hooks/useDocs";
import { useT } from "@/i18n";
+import { openExternalUrl } from "@/lib/openExternal";
+import { ONLINE_DOCS_URL, SearchTrigger } from "./docsShared";
interface Props {
selectedSlug: string | null;
@@ -26,6 +15,11 @@ interface Props {
onOpenSearch: () => void;
}
+/**
+ * The docs navigation: one search field, an Overview entry, then every topic
+ * as a collapsible group of plain text links. No per-row icons or counts —
+ * the titles carry the navigation, the active row carries the accent.
+ */
export function DocsSidebar({
selectedSlug,
onSelect,
@@ -34,244 +28,174 @@ export function DocsSidebar({
}: Props) {
const t = useT();
const { data, isLoading, isFetching, error, refetch } = useDocsGrouped();
- const { recent } = useRecentDocs();
- const [query, setQuery] = useState("");
const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
const sections = useMemo(() => buildDocSections(data), [data]);
- const filteredSections = useMemo(() => {
- const q = query.trim().toLowerCase();
- if (!q) return sections;
- return sections
- .map((section) => ({
- ...section,
- docs: section.docs.filter(
- (d) =>
- d.title.toLowerCase().includes(q) ||
- d.summary.toLowerCase().includes(q) ||
- d.slug.toLowerCase().includes(q) ||
- d.tags.some((t) => t.toLowerCase().includes(q)),
- ),
- }))
- .filter((section) => section.docs.length > 0);
- }, [query, sections]);
+ // Opening a guide from search or a cross-link re-opens its group, so the
+ // active row is never hidden inside a collapsed topic.
+ useEffect(() => {
+ if (!selectedSlug) return;
+ const owner = sections.find((section) =>
+ section.docs.some((doc) => doc.slug === selectedSlug),
+ );
+ if (!owner) return;
+ setCollapsed((prev) => {
+ if (!prev.has(owner.name)) return prev;
+ const next = new Set(prev);
+ next.delete(owner.name);
+ return next;
+ });
+ }, [selectedSlug, sections]);
- const totalCount = useMemo(() => {
- return filteredSections.reduce((acc, section) => acc + section.docs.length, 0);
- }, [filteredSections]);
+ const toggle = (name: string) => {
+ setCollapsed((prev) => {
+ const next = new Set(prev);
+ if (next.has(name)) next.delete(name);
+ else next.add(name);
+ return next;
+ });
+ };
- // A standing rail, not a card: it runs the full height of the section, so it
- // takes the rail ground and separates from the page by fill alone — a
- // content-sized surface is what earns --card, and this is not one.
return (
- <aside className="flex h-full w-72 shrink-0 flex-col border-r border-border bg-sidebar">
- {/* Header */}
- <div className="border-b border-border px-3 py-3">
- <div className="mb-2 flex items-center justify-between">
- <button
- type="button"
- onClick={onShowOverview}
- className="rounded-sm text-base font-semibold text-foreground-strong transition-colors hover:text-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
- >
- {t("docs_sidebar.title")}
- </button>
- <button
- type="button"
- onClick={onOpenSearch}
- title={t("docs.fulltext_search")}
- aria-label={t("docs.fulltext_search")}
- className="rounded-md p-1.5 text-muted-foreground transition hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
- >
- <Search className="h-4 w-4" aria-hidden="true" />
- </button>
- </div>
- <label htmlFor="docs-sidebar-filter" className="sr-only">
- {t("docs.search_placeholder")}
- </label>
- <input
- id="docs-sidebar-filter"
- name="docs-filter"
- type="text"
- placeholder={t("docs.search_placeholder")}
- autoComplete="off"
- value={query}
- onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
- setQuery(e.target.value)
- }
- className="flex h-9 w-full rounded-md border border-border-strong bg-input px-3 text-base ring-offset-sidebar placeholder:text-foreground-faint transition-colors focus-visible:border-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
- />
- {isLoading ? (
- <div
- className="mt-2 flex items-center gap-2 text-xs text-muted-foreground"
- role="status"
- >
- <Loader2 className="h-3 w-3 animate-spin text-primary motion-reduce:animate-none" aria-hidden="true" />
- <span>{t("docs_sidebar.indexing")}</span>
- </div>
- ) : error ? (
- <button
- type="button"
- onClick={() => void refetch()}
- className="mt-2 inline-flex items-center gap-1.5 text-xs text-destructive transition hover:text-destructive/80"
- >
- <RefreshCw
- className={cn(
- "h-3 w-3",
- isFetching && "animate-spin motion-reduce:animate-none",
- )}
- aria-hidden="true"
- />
- {t("docs_sidebar.retry")}
- </button>
- ) : (
- <p className="mt-2 text-sm text-foreground-faint">
- {totalCount} {t("docs_sidebar.documents")}
- </p>
- )}
+ <aside
+ aria-label={t("docs_sidebar.title")}
+ className="flex h-full w-64 shrink-0 flex-col border-r border-border bg-background"
+ >
+ <div className="px-4 pb-3 pt-5">
+ <SearchTrigger onClick={onOpenSearch} />
</div>
- {/* Tree */}
<ScrollArea className="flex-1">
- <div className="px-2 py-2">
+ <nav className="px-3 pb-6">
+ <NavRow
+ label={t("docs_sidebar.overview")}
+ active={selectedSlug === null}
+ onClick={onShowOverview}
+ />
+
{isLoading && <SidebarSkeleton />}
- {/* Recent docs — only when not filtered + at least 1 entry */}
- {!isLoading && !query && recent.length > 0 && (
- <div className="mb-2">
- <div className="mb-1 flex h-6 w-full items-center gap-1 rounded-sm px-3 text-xs font-medium uppercase tracking-wide text-foreground-faint">
- <Clock className="h-3 w-3" aria-hidden="true" />
- <span>{t("docs.recent")}</span>
- <span className="ml-auto text-xs font-normal normal-case tracking-normal">
- {recent.length}
- </span>
- </div>
- {recent.map((doc) => (
+ {error && !isLoading && (
+ <button
+ type="button"
+ onClick={() => void refetch()}
+ className="mt-4 inline-flex items-center gap-1.5 rounded-sm px-3 text-sm text-destructive transition-colors hover:text-destructive/80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ <RefreshCw
+ className={cn(
+ "h-3 w-3",
+ isFetching && "animate-spin motion-reduce:animate-none",
+ )}
+ aria-hidden="true"
+ />
+ {t("docs_sidebar.retry")}
+ </button>
+ )}
+
+ {sections.map((section) => {
+ const isCollapsed = collapsed.has(section.name);
+ const groupId = `docs-nav-${section.order}-${section.docs[0]?.slug ?? "group"}`;
+ return (
+ <div key={section.name} className="mt-5">
<button
- key={doc.slug}
type="button"
- onClick={() => onSelect(doc.slug)}
- data-active={doc.slug === selectedSlug || undefined}
- className={cn(
- "flex min-h-8 w-full items-start gap-2 rounded-md px-3 py-1.5 text-left text-base text-muted-foreground transition-colors",
- "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
- doc.slug === selectedSlug && "jarvis-nav-active bg-secondary font-medium text-foreground",
- )}
- title={doc.title}
+ onClick={() => toggle(section.name)}
+ aria-expanded={!isCollapsed}
+ aria-controls={groupId}
+ className="group flex w-full items-center justify-between gap-2 rounded-sm px-3 py-1 text-left text-sm font-semibold text-foreground-strong focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
>
- <FileText className="mt-1 h-3.5 w-3.5 shrink-0" aria-hidden="true" />
- <span className="flex-1 break-words line-clamp-2">
- {doc.title}
- </span>
- </button>
- ))}
- <div className="my-2 border-b border-border/40" />
- </div>
- )}
-
- {filteredSections.map((section) => {
- const isCollapsed = collapsed.has(section.name);
- return (
- <div key={section.name} className="mb-2">
- <button
- type="button"
- onClick={() => {
- const next = new Set(collapsed);
- if (isCollapsed) next.delete(section.name);
- else next.add(section.name);
- setCollapsed(next);
- }}
- aria-expanded={!isCollapsed}
- className="group mb-1 mt-4 flex h-6 w-full items-center gap-1 rounded-sm px-3 text-xs font-medium uppercase tracking-wide text-foreground-faint transition-colors hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
- >
- {isCollapsed ? (
- <ChevronRight className="h-3 w-3" aria-hidden="true" />
- ) : (
- <ChevronDown className="h-3 w-3" aria-hidden="true" />
+ <span>{section.name}</span>
+ <ChevronDown
+ className={cn(
+ "h-3.5 w-3.5 shrink-0 text-foreground-faint opacity-0 transition group-hover:opacity-100 group-focus-visible:opacity-100",
+ isCollapsed && "-rotate-90 opacity-100",
)}
- <span>{section.name}</span>
- <span className="ml-auto text-xs font-normal normal-case tracking-normal">
- {section.docs.length}
- </span>
- </button>
- {!isCollapsed &&
- section.docs.map((doc) => (
- <SidebarItem
- key={doc.slug}
- doc={doc}
- active={doc.slug === selectedSlug}
- onClick={() => onSelect(doc.slug)}
- />
+ aria-hidden="true"
+ />
+ </button>
+ {!isCollapsed && (
+ <ul id={groupId} className="mt-1 space-y-px">
+ {section.docs.map((doc) => (
+ <li key={doc.slug}>
+ <NavRow
+ label={doc.title}
+ active={doc.slug === selectedSlug}
+ onClick={() => onSelect(doc.slug)}
+ />
+ </li>
))}
- </div>
- );
- })}
-
- {!isLoading && !error && totalCount === 0 && (
- <div className="px-3 py-8 text-center text-base text-muted-foreground">
- {t("docs_sidebar.no_results")}
- </div>
- )}
- </div>
+ </ul>
+ )}
+ </div>
+ );
+ })}
+ </nav>
</ScrollArea>
+
+ <div className="border-t border-border px-4 py-3">
+ <a
+ href={ONLINE_DOCS_URL}
+ onClick={(event) => {
+ event.preventDefault();
+ void openExternalUrl(ONLINE_DOCS_URL);
+ }}
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-1.5 rounded-sm text-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ >
+ {t("docs_sidebar.github")}
+ <ExternalLink className="h-3 w-3" aria-hidden="true" />
+ </a>
+ </div>
</aside>
);
}
-interface ItemProps {
- doc: DocNavSummary;
+function NavRow({
+ label,
+ active,
+ onClick,
+}: {
+ label: string;
active: boolean;
onClick: () => void;
+}) {
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ data-active={active || undefined}
+ aria-current={active ? "page" : undefined}
+ title={label}
+ className={cn(
+ "block w-full rounded-md px-3 py-1.5 text-left text-base text-muted-foreground transition-colors",
+ "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ active && "jarvis-nav-active font-medium",
+ )}
+ >
+ <span className="line-clamp-2 break-words">{label}</span>
+ </button>
+ );
}
function SidebarSkeleton() {
return (
<div
- className="animate-pulse space-y-5 px-2 py-2 motion-reduce:animate-none"
+ className="mt-5 animate-pulse space-y-6 px-3 motion-reduce:animate-none"
aria-hidden="true"
>
- {[4, 3, 5].map((rows, group) => (
- <div key={group} className="space-y-2">
- <div className="h-2 w-24 rounded-full bg-muted" />
+ {[5, 4, 6].map((rows, group) => (
+ <div key={group} className="space-y-3">
+ <div className="h-2.5 w-24 rounded-full bg-muted" />
{Array.from({ length: rows }, (_, row) => (
- <div key={row} className="flex items-center gap-2 py-1">
- <div className="h-3 w-3 rounded-sm bg-muted/80" />
- <div
- className="h-2.5 rounded-full bg-muted/80"
- style={{ width: `${58 + ((row + group) % 3) * 12}%` }}
- />
- </div>
+ <div
+ key={row}
+ className="h-2.5 rounded-full bg-muted/70"
+ style={{ width: `${55 + ((row + group) % 3) * 14}%` }}
+ />
))}
</div>
))}
</div>
);
}
-
-function SidebarItem({ doc, active, onClick }: ItemProps) {
- // Doc titles should be fully readable (user mandate 2026-04-29) —
- // ``break-words`` allows wrapping inside German compound words,
- // ``line-clamp-2`` caps it at 2 lines max so the list doesn't sprawl, and
- // the ``title`` attribute stays as a hover tooltip for the full title.
- // NO Diataxis pill — the section header above already carries that info
- // (user mandate: no duplicate information, no truncated ``LEGAC...`` pill).
- return (
- <button
- type="button"
- onClick={onClick}
- data-active={active || undefined}
- aria-current={active ? "page" : undefined}
- className={cn(
- "flex min-h-8 w-full items-start gap-2 rounded-md px-3 py-1.5 text-left text-base text-muted-foreground transition-colors",
- "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
- active && "jarvis-nav-active bg-secondary font-medium text-foreground",
- )}
- title={doc.title}
- >
- <FileText className="mt-1 h-3.5 w-3.5 shrink-0" aria-hidden="true" />
- <span className="flex-1 break-words line-clamp-2">
- {doc.title}
- </span>
- </button>
- );
-}
diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsx
index 983c583c88..4a4e96f22c 100644
--- a/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsx
+++ b/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsx
@@ -1,6 +1,6 @@
import { useEffect, useMemo, useState } from "react";
+import { AlignLeft } from "lucide-react";
-import { ScrollArea } from "@/components/ui/scroll-area";
import { cn } from "@/lib/utils";
import type { DocHeading } from "@/hooks/useDocs";
import { useT } from "@/i18n";
@@ -13,7 +13,7 @@ interface Props {
/**
* Right-sidebar table of contents with active-heading tracking via
- * IntersectionObserver — Anthropic/Mintlify style.
+ * IntersectionObserver.
*
* Reacts to H2 + H3. H4-H6 are rare in our docs but could be added here if
* needed. The active-heading trigger is shifted by the heading height via
@@ -40,6 +40,7 @@ export function DocsToc({ headings, contentRef }: Props) {
if (el) observed.push(el);
}
if (!observed.length) return;
+ setActiveSlug(observed[0].id);
const observer = new IntersectionObserver(
(entries) => {
@@ -64,46 +65,60 @@ export function DocsToc({ headings, contentRef }: Props) {
);
for (const el of observed) observer.observe(el);
- return () => observer.disconnect();
+
+ // The last sections of a page can be too short to ever reach the top
+ // band; once the reader hits the bottom, the final heading is current.
+ const onScroll = () => {
+ const atBottom =
+ container.scrollTop + container.clientHeight >= container.scrollHeight - 4;
+ if (atBottom) setActiveSlug(observed[observed.length - 1].id);
+ };
+ container.addEventListener("scroll", onScroll, { passive: true });
+ return () => {
+ observer.disconnect();
+ container.removeEventListener("scroll", onScroll);
+ };
}, [tocHeadings, contentRef]);
if (!tocHeadings.length) {
return null;
}
+ // Sticky inside the docs scroller, so it travels beside the article
+ // instead of hugging the window edge.
return (
- <aside
- className="hidden h-full w-64 shrink-0 border-l border-border xl:block"
+ <nav
+ className="sticky top-0 hidden max-h-screen w-56 shrink-0 self-start overflow-y-auto pb-10 pt-12 xl:block"
aria-label={t("docs_content.on_this_page")}
>
- <ScrollArea className="h-full">
- <div className="px-4 py-6">
- <h3 className="mb-3 text-micro font-semibold uppercase tracking-wider text-muted-foreground">
- {t("docs_content.on_this_page")}
- </h3>
- <ul className="space-y-1 text-xs">
- {tocHeadings.map((h) => (
- <li key={h.slug}>
- <a
- href={`#${h.slug}`}
- onClick={(e) => handleClick(e, h.slug)}
- aria-current={activeSlug === h.slug ? "location" : undefined}
- className={cn(
- "block rounded py-0.5 transition",
- "text-muted-foreground hover:text-foreground",
- h.level === 3 && "ml-3",
- activeSlug === h.slug &&
- "border-l-2 border-primary pl-2 -ml-px font-medium text-foreground",
- )}
- >
- {h.text}
- </a>
- </li>
- ))}
- </ul>
- </div>
- </ScrollArea>
- </aside>
+ <p className="mb-3 flex items-center gap-2 text-sm font-semibold text-foreground-strong">
+ <AlignLeft className="h-3.5 w-3.5 text-muted-foreground" aria-hidden="true" />
+ {t("docs_content.on_this_page")}
+ </p>
+ <ul className="border-l border-border text-sm">
+ {tocHeadings.map((h) => {
+ const active = activeSlug === h.slug;
+ return (
+ <li key={h.slug}>
+ <a
+ href={`#${h.slug}`}
+ onClick={(e) => handleClick(e, h.slug)}
+ aria-current={active ? "location" : undefined}
+ className={cn(
+ "-ml-px block border-l py-1 pr-2 transition-colors",
+ h.level === 3 ? "pl-7" : "pl-4",
+ active
+ ? "border-accent font-medium text-accent"
+ : "border-transparent text-muted-foreground hover:border-border-strong hover:text-foreground",
+ )}
+ >
+ {h.text}
+ </a>
+ </li>
+ );
+ })}
+ </ul>
+ </nav>
);
}
diff --git a/jarvis/ui/web/frontend/src/components/docs/docsShared.tsx b/jarvis/ui/web/frontend/src/components/docs/docsShared.tsx
new file mode 100644
index 0000000000..65106f5c41
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/docs/docsShared.tsx
@@ -0,0 +1,103 @@
+import {
+ BookOpen,
+ Blocks,
+ FileCode2,
+ FileText,
+ MessageSquare,
+ Rocket,
+ Search,
+ ShieldCheck,
+ SlidersHorizontal,
+ type LucideIcon,
+} from "lucide-react";
+
+import { isMacClient } from "@/lib/embeddedDesktop";
+import { cn } from "@/lib/utils";
+import { useT } from "@/i18n";
+
+/** Where the Markdown sources of the bundled docs live publicly. */
+export const DOCS_REPO_URL = "https://github.com/PersonalJarvis/PersonalJarvis";
+export const ONLINE_DOCS_URL = `${DOCS_REPO_URL}/tree/main/docs`;
+
+/** Public URL of one guide's source file (``path`` is repo-relative). */
+export function docSourceUrl(path: string): string {
+ return `${DOCS_REPO_URL}/blob/main/${path.replace(/^\/+/, "")}`;
+}
+
+/**
+ * One quiet glyph per topic. Section names come from the guides' front
+ * matter, so the lookup is by keyword and any unknown section falls back to a
+ * plain page glyph instead of failing.
+ */
+const SECTION_ICONS: Array<[RegExp, LucideIcon]> = [
+ [/start/i, Rocket],
+ [/everyday|use/i, MessageSquare],
+ [/personali[sz]e|connect/i, SlidersHorizontal],
+ [/knowledge|shar/i, BookOpen],
+ [/extend|automat/i, Blocks],
+ [/privacy|safety|support/i, ShieldCheck],
+ [/reference/i, FileCode2],
+];
+
+export function sectionIcon(name: string): LucideIcon {
+ for (const [pattern, icon] of SECTION_ICONS) {
+ if (pattern.test(name)) return icon;
+ }
+ return FileText;
+}
+
+/** The platform's own name for the search chord. */
+export function searchShortcutLabel(): string {
+ const mac =
+ typeof navigator !== "undefined" && isMacClient(navigator.userAgent);
+ return mac ? "⌘K" : "Ctrl K";
+}
+
+/** Rounded-up reading time at a calm 220 words per minute. */
+export function readingMinutes(markdown: string): number {
+ const words = markdown
+ .replace(/```[\s\S]*?```/g, " ")
+ .split(/\s+/)
+ .filter(Boolean).length;
+ return Math.max(1, Math.ceil(words / 220));
+}
+
+/**
+ * The search trigger: reads as a field, opens the full-text search dialog.
+ * ``size="lg"`` is the hero variant on the docs home.
+ */
+export function SearchTrigger({
+ onClick,
+ size = "md",
+ className,
+}: {
+ onClick: () => void;
+ size?: "md" | "lg";
+ className?: string;
+}) {
+ const t = useT();
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ aria-label={t("docs.search_modal_title")}
+ className={cn(
+ "group flex w-full items-center gap-2.5 rounded-md border border-border bg-input text-left text-muted-foreground transition-colors",
+ "hover:border-border-strong hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ size === "lg" ? "h-11 px-4 text-lg" : "h-9 px-3 text-base",
+ className,
+ )}
+ >
+ <Search
+ className={cn("shrink-0", size === "lg" ? "h-4 w-4" : "h-3.5 w-3.5")}
+ aria-hidden="true"
+ />
+ <span className="flex-1 truncate">
+ {size === "lg" ? t("docs.search_hero") : t("docs.search_button")}
+ </span>
+ <kbd className="shrink-0 rounded-sm border border-border bg-background px-1.5 py-0.5 font-sans text-xs font-medium text-foreground-faint">
+ {searchShortcutLabel()}
+ </kbd>
+ </button>
+ );
+}
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/de.json b/jarvis/ui/web/frontend/src/i18n/locales/de.json
index 1a8735774c..7086354819 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/de.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/de.json
@@ -3246,7 +3246,9 @@
"no_results": "Keine Treffer für \"{0}\"",
"for_fulltext": "für die Volltextsuche.",
"could_not_load": "Konnte Doc nicht laden.",
- "recent": "Zuletzt"
+ "recent": "Zuletzt",
+ "search_button": "Doku durchsuchen",
+ "search_hero": "Dokumentation durchsuchen"
},
"sessions": {
"select_one": "Wähle links eine Session aus.",
@@ -3671,7 +3673,9 @@
"indexing": "Lokaler Index wird erstellt…",
"retry": "Erneut versuchen",
"documents": "Dokumente",
- "no_results": "Keine passenden Dokumente"
+ "no_results": "Keine passenden Dokumente",
+ "overview": "Übersicht",
+ "github": "Doku auf GitHub"
},
"docs_content": {
"prev": "Vorher",
@@ -3683,27 +3687,46 @@
"on_this_page": "Auf dieser Seite",
"copy_code": "Code kopieren",
"code_copied": "Code kopiert",
- "skip_to_content": "Zum Dokumentationsinhalt springen"
+ "skip_to_content": "Zum Dokumentationsinhalt springen",
+ "reading_time": "{0} Min. Lesezeit",
+ "reviewed": "Geprüft am {0}",
+ "copy_page": "Seite kopieren",
+ "page_copied": "Kopiert",
+ "view_source": "Quelle ansehen",
+ "copy": "Kopieren",
+ "pagination": "Vorherige und nächste Anleitung",
+ "callout_note": "Hinweis",
+ "callout_info": "Info",
+ "callout_tip": "Tipp",
+ "callout_warning": "Warnung"
},
"docs_overview": {
"eyebrow": "Dokumentation",
- "title": "Personal Jarvis Docs",
- "description": "Alles von der ersten Einrichtung bis zur Architektur hinter der Sprachsteuerung. Durchsuche die vollständige lokale Bibliothek oder öffne die neu gestaltete öffentliche Dokumentation.",
- "online_docs": "Neu gestaltete Online-Docs öffnen",
+ "title": "Personal Jarvis Dokumentation",
+ "description": "Anleitungen, Konzepte und Referenzen zum Einrichten, Nutzen und Erweitern deines Assistenten.",
+ "online_docs": "Auf GitHub ansehen",
"load_failed_title": "Die Dokumentation konnte nicht geladen werden",
"load_failed_description": "Der lokale Index wurde nicht rechtzeitig bereit. Versuch es erneut, ohne die App neu zu starten.",
"retry": "Erneut versuchen",
"empty_title": "Keine lokalen Dokumente gefunden",
- "empty_description": "Die Online-Dokumentation ist weiterhin über die Schaltfläche oben erreichbar.",
+ "empty_description": "Die Dokumentation ist auch auf GitHub verfügbar.",
"local_library": "In der lokalen Bibliothek starten",
"local_library_description": "Schneller Offline-Zugriff auf die Dokumentation dieser Installation.",
"indexing_title": "Deine Dokumentation wird vorbereitet",
"indexing_description": "Die lokale Markdown-Bibliothek wird gelesen und die Volltextsuche aufgebaut. Das dauert normalerweise nur einen Moment.",
"loading_page": "Dokument wird geladen…",
- "browse_by_topic": "Nach Thema durchsuchen",
- "browse_description": "Folge einem Lernpfad oder springe direkt zum benötigten Feature.",
+ "browse_by_topic": "Nach Thema stöbern",
+ "browse_description": "Alle Anleitungen dieser Installation, sortiert nach dem, was du vorhast.",
"guide": "Anleitung",
- "guides": "Anleitungen"
+ "guides": "Anleitungen",
+ "start_title": "Erste Schritte",
+ "start_description": "Neu hier? Lies diese Anleitungen der Reihe nach – von der Installation bis zu deinem ersten Sprachgespräch.",
+ "start_reading": "Jetzt lesen",
+ "recent_title": "Weiterlesen, wo du aufgehört hast",
+ "show_all": "Alle {0} anzeigen",
+ "show_less": "Weniger anzeigen",
+ "help_title": "Nicht gefunden, was du suchst?",
+ "help_description": "Durchsuche alle Anleitungen nach Stichworten oder sieh dir die Quellen auf GitHub an."
},
"docs_search_modal": {
"navigate": "navigieren",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/en.json b/jarvis/ui/web/frontend/src/i18n/locales/en.json
index 0943d74fda..f3014b2ed5 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/en.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/en.json
@@ -3246,7 +3246,9 @@
"no_results": "No results for \"{0}\"",
"for_fulltext": "for full-text search.",
"could_not_load": "Could not load doc.",
- "recent": "Recent"
+ "recent": "Recent",
+ "search_button": "Search docs",
+ "search_hero": "Search the documentation"
},
"sessions": {
"select_one": "Select a session on the left.",
@@ -3671,7 +3673,9 @@
"indexing": "Building local index…",
"retry": "Try again",
"documents": "documents",
- "no_results": "No matching documents"
+ "no_results": "No matching documents",
+ "overview": "Overview",
+ "github": "Docs on GitHub"
},
"docs_content": {
"prev": "Previous",
@@ -3683,27 +3687,46 @@
"on_this_page": "On this page",
"copy_code": "Copy code",
"code_copied": "Code copied",
- "skip_to_content": "Skip to documentation content"
+ "skip_to_content": "Skip to documentation content",
+ "reading_time": "{0} min read",
+ "reviewed": "Reviewed {0}",
+ "copy_page": "Copy page",
+ "page_copied": "Copied",
+ "view_source": "View source",
+ "copy": "Copy",
+ "pagination": "Previous and next guide",
+ "callout_note": "Note",
+ "callout_info": "Info",
+ "callout_tip": "Tip",
+ "callout_warning": "Warning"
},
"docs_overview": {
"eyebrow": "Documentation",
- "title": "Personal Jarvis docs",
- "description": "Everything from first setup to the architecture behind the voice. Browse the complete local library or open the redesigned public documentation.",
- "online_docs": "Open redesigned online docs",
+ "title": "Personal Jarvis documentation",
+ "description": "Guides, concepts, and reference for setting up, using, and extending your assistant.",
+ "online_docs": "View on GitHub",
"load_failed_title": "Documentation could not be loaded",
"load_failed_description": "The local index did not become ready in time. Try again without restarting the app.",
"retry": "Try again",
"empty_title": "No local documents found",
- "empty_description": "The online documentation is still available from the button above.",
+ "empty_description": "The documentation is also available on GitHub.",
"local_library": "Start in the local library",
"local_library_description": "Fast, offline access to the documentation shipped with this installation.",
"indexing_title": "Preparing your documentation",
"indexing_description": "Scanning the local Markdown library and building full-text search. This usually takes only a moment.",
"loading_page": "Loading document…",
- "browse_by_topic": "Browse by Topic",
- "browse_description": "Follow a learning path or jump to the feature you need.",
+ "browse_by_topic": "Browse by topic",
+ "browse_description": "Every guide that ships with this installation, grouped by what you want to do.",
"guide": "guide",
- "guides": "guides"
+ "guides": "guides",
+ "start_title": "Get started",
+ "start_description": "New here? Read these guides in order, from installing the app to your first voice conversation.",
+ "start_reading": "Start reading",
+ "recent_title": "Pick up where you left off",
+ "show_all": "Show all {0}",
+ "show_less": "Show less",
+ "help_title": "Can't find what you need?",
+ "help_description": "Search every guide by keyword, or browse the sources on GitHub."
},
"docs_search_modal": {
"navigate": "navigate",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/es.json b/jarvis/ui/web/frontend/src/i18n/locales/es.json
index c3f1795e2a..c9c8be79b8 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/es.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/es.json
@@ -3246,7 +3246,9 @@
"no_results": "Sin resultados para \"{0}\"",
"for_fulltext": "para la búsqueda completa.",
"could_not_load": "No se pudo cargar el documento.",
- "recent": "Recientes"
+ "recent": "Recientes",
+ "search_button": "Buscar en la documentación",
+ "search_hero": "Buscar en la documentación"
},
"sessions": {
"select_one": "Selecciona una sesión a la izquierda.",
@@ -3671,7 +3673,9 @@
"indexing": "Creando el índice local…",
"retry": "Intentar de nuevo",
"documents": "documentos",
- "no_results": "No hay documentos coincidentes"
+ "no_results": "No hay documentos coincidentes",
+ "overview": "Resumen",
+ "github": "Documentación en GitHub"
},
"docs_content": {
"prev": "Anterior",
@@ -3683,27 +3687,46 @@
"on_this_page": "En esta página",
"copy_code": "Copiar código",
"code_copied": "Código copiado",
- "skip_to_content": "Saltar al contenido de la documentación"
+ "skip_to_content": "Saltar al contenido de la documentación",
+ "reading_time": "{0} min de lectura",
+ "reviewed": "Revisado el {0}",
+ "copy_page": "Copiar página",
+ "page_copied": "Copiado",
+ "view_source": "Ver fuente",
+ "copy": "Copiar",
+ "pagination": "Guía anterior y siguiente",
+ "callout_note": "Nota",
+ "callout_info": "Información",
+ "callout_tip": "Consejo",
+ "callout_warning": "Advertencia"
},
"docs_overview": {
"eyebrow": "Documentación",
"title": "Documentación de Personal Jarvis",
- "description": "Todo, desde la configuración inicial hasta la arquitectura de la voz. Explora la biblioteca local completa o abre la documentación pública rediseñada.",
- "online_docs": "Abrir la documentación web rediseñada",
+ "description": "Guías, conceptos y referencias para configurar, usar y ampliar tu asistente.",
+ "online_docs": "Ver en GitHub",
"load_failed_title": "No se pudo cargar la documentación",
"load_failed_description": "El índice local no estuvo listo a tiempo. Inténtalo de nuevo sin reiniciar la aplicación.",
"retry": "Intentar de nuevo",
"empty_title": "No se encontraron documentos locales",
- "empty_description": "La documentación web sigue disponible mediante el botón de arriba.",
+ "empty_description": "La documentación también está disponible en GitHub.",
"local_library": "Empieza en la biblioteca local",
"local_library_description": "Acceso rápido y sin conexión a la documentación incluida en esta instalación.",
"indexing_title": "Preparando tu documentación",
"indexing_description": "Se está leyendo la biblioteca Markdown local y creando la búsqueda de texto completo. Normalmente solo tarda un momento.",
"loading_page": "Cargando documento…",
"browse_by_topic": "Explorar por tema",
- "browse_description": "Sigue una ruta de aprendizaje o ve directamente a la función que necesitas.",
+ "browse_description": "Todas las guías incluidas en esta instalación, agrupadas según lo que quieras hacer.",
"guide": "guía",
- "guides": "guías"
+ "guides": "guías",
+ "start_title": "Primeros pasos",
+ "start_description": "¿Eres nuevo? Lee estas guías en orden, desde la instalación hasta tu primera conversación por voz.",
+ "start_reading": "Empezar a leer",
+ "recent_title": "Continúa donde lo dejaste",
+ "show_all": "Mostrar las {0}",
+ "show_less": "Mostrar menos",
+ "help_title": "¿No encuentras lo que buscas?",
+ "help_description": "Busca en todas las guías por palabra clave o consulta las fuentes en GitHub."
},
"docs_search_modal": {
"navigate": "navegar",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/zh.json b/jarvis/ui/web/frontend/src/i18n/locales/zh.json
index 947593e9f1..1929aaa07a 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/zh.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/zh.json
@@ -3248,7 +3248,9 @@
"no_results": "没有找到“{0}”的结果",
"for_fulltext": "进行全文搜索。",
"could_not_load": "无法加载文档。",
- "recent": "最近"
+ "recent": "最近",
+ "search_button": "搜索文档",
+ "search_hero": "搜索文档"
},
"sessions": {
"select_one": "请在左侧选择一个会话。",
@@ -3673,7 +3675,9 @@
"indexing": "正在建立本地索引…",
"retry": "重试",
"documents": "篇文档",
- "no_results": "没有匹配的文档"
+ "no_results": "没有匹配的文档",
+ "overview": "概览",
+ "github": "GitHub 上的文档"
},
"docs_content": {
"prev": "上一篇",
@@ -3685,27 +3689,46 @@
"on_this_page": "本页内容",
"copy_code": "复制代码",
"code_copied": "代码已复制",
- "skip_to_content": "跳到文档内容"
+ "skip_to_content": "跳到文档内容",
+ "reading_time": "阅读约 {0} 分钟",
+ "reviewed": "审阅于 {0}",
+ "copy_page": "复制页面",
+ "page_copied": "已复制",
+ "view_source": "查看源文件",
+ "copy": "复制",
+ "pagination": "上一篇和下一篇指南",
+ "callout_note": "注意",
+ "callout_info": "信息",
+ "callout_tip": "提示",
+ "callout_warning": "警告"
},
"docs_overview": {
"eyebrow": "文档",
"title": "Personal Jarvis 文档",
- "description": "从首次设置到语音背后的架构,一应俱全。浏览完整的本地文档库,或打开全新设计的在线文档。",
- "online_docs": "打开全新的在线文档",
+ "description": "设置、使用和扩展你的助手所需的指南、概念与参考资料。",
+ "online_docs": "在 GitHub 上查看",
"load_failed_title": "无法加载文档",
"load_failed_description": "本地索引未能及时就绪。无需重启应用,直接重试即可。",
"retry": "重试",
"empty_title": "未找到本地文档",
- "empty_description": "你仍然可以通过上方按钮访问在线文档。",
+ "empty_description": "文档也可以在 GitHub 上查看。",
"local_library": "从本地文档库开始",
"local_library_description": "快速、离线地访问此安装附带的文档。",
"indexing_title": "正在准备你的文档",
"indexing_description": "正在扫描本地 Markdown 文档库并建立全文搜索。通常只需片刻。",
"loading_page": "正在加载文档…",
"browse_by_topic": "按主题浏览",
- "browse_description": "沿着学习路径前进,或直接跳到你需要的功能。",
+ "browse_description": "本次安装附带的所有指南,按你想完成的事情分组。",
"guide": "篇指南",
- "guides": "篇指南"
+ "guides": "篇指南",
+ "start_title": "快速开始",
+ "start_description": "刚开始使用?按顺序阅读这些指南,从安装应用到第一次语音对话。",
+ "start_reading": "开始阅读",
+ "recent_title": "从上次离开的地方继续",
+ "show_all": "显示全部 {0} 篇",
+ "show_less": "收起",
+ "help_title": "没有找到需要的内容?",
+ "help_description": "按关键词搜索所有指南,或在 GitHub 上浏览源文件。"
},
"docs_search_modal": {
"navigate": "导航",
diff --git a/jarvis/ui/web/frontend/src/index.css b/jarvis/ui/web/frontend/src/index.css
index bee7361903..cccd900132 100644
--- a/jarvis/ui/web/frontend/src/index.css
+++ b/jarvis/ui/web/frontend/src/index.css
@@ -949,6 +949,53 @@ body {
--tw-prose-invert-links: hsl(var(--accent));
}
+/* A docs guide reads from theme tokens only, so the same class list serves
+ light and dark; the plugin's inverted palette is pointed at the same
+ values. Body copy sits one step below heading ink. */
+.docs-prose {
+ --tw-prose-body: hsl(var(--foreground-secondary));
+ --tw-prose-headings: hsl(var(--foreground-strong));
+ --tw-prose-lead: hsl(var(--muted-foreground));
+ --tw-prose-bold: hsl(var(--foreground-strong));
+ --tw-prose-counters: hsl(var(--muted-foreground));
+ --tw-prose-bullets: hsl(var(--foreground-faint));
+ --tw-prose-hr: hsl(var(--border));
+ --tw-prose-quotes: hsl(var(--foreground-secondary));
+ --tw-prose-quote-borders: hsl(var(--border-strong));
+ --tw-prose-code: hsl(var(--foreground-strong));
+ --tw-prose-th-borders: hsl(var(--border));
+ --tw-prose-td-borders: hsl(var(--border));
+ --tw-prose-invert-body: hsl(var(--foreground-secondary));
+ --tw-prose-invert-headings: hsl(var(--foreground-strong));
+ --tw-prose-invert-bold: hsl(var(--foreground-strong));
+ --tw-prose-invert-bullets: hsl(var(--foreground-faint));
+ --tw-prose-invert-hr: hsl(var(--border));
+ --tw-prose-invert-code: hsl(var(--foreground-strong));
+ font-size: 16px;
+ line-height: 28px;
+ letter-spacing: 0;
+}
+
+/* Headings are wrapped in their own anchor (rehype-autolink-headings). The
+ anchor keeps heading ink and reveals a quiet "#" on hover, so a section
+ link can be copied without turning every heading into link colour. */
+.docs-prose :is(h2, h3, h4) > a {
+ color: inherit;
+ font-weight: inherit;
+ text-decoration: none;
+}
+.docs-prose :is(h2, h3, h4) > a::after {
+ content: "#";
+ margin-left: 0.4em;
+ color: hsl(var(--foreground-faint));
+ opacity: 0;
+ transition: opacity 120ms ease;
+}
+.docs-prose :is(h2, h3, h4):hover > a::after,
+.docs-prose :is(h2, h3, h4) > a:focus-visible::after {
+ opacity: 1;
+}
+
/* Selecting text answers in the theme's own material, not the engine's
default blue — the one saturated slab a black-and-white product used to
show every time someone dragged across a sentence. */
diff --git a/jarvis/ui/web/frontend/src/views/DocsView.tsx b/jarvis/ui/web/frontend/src/views/DocsView.tsx
index 72220d58c0..8b4c64f31b 100644
--- a/jarvis/ui/web/frontend/src/views/DocsView.tsx
+++ b/jarvis/ui/web/frontend/src/views/DocsView.tsx
@@ -9,9 +9,9 @@ import { useRecentDocs } from "@/hooks/useRecentDocs";
import { useT } from "@/i18n";
/**
- * Top-level view for the docs section. 3-column layout (Anthropic/Mintlify style):
- * left sidebar = Diataxis tree, middle = Markdown body, right = TOC with
- * active-heading spy.
+ * Top-level view for the docs section. The navigation rail stays put on the
+ * left; the article and its "On this page" list share one centred scroller,
+ * so the table of contents travels beside the text at every window width.
*
* ``selectedSlug`` is view-local — not a state-store entry, because the doc
* only matters within this view. When switching sections we deliberately
@@ -106,15 +106,22 @@ export function DocsView() {
id="docs-content"
ref={contentRef as React.RefObject<HTMLElement>}
tabIndex={-1}
- className="min-w-0 flex-1 overflow-y-auto"
+ className="min-w-0 flex-1 overflow-y-auto focus-visible:outline-none"
>
- <DocsContent
- slug={selectedSlug}
- onSelect={selectDoc}
- onShowOverview={showOverview}
- />
+ <div className="mx-auto flex w-full max-w-6xl gap-12 px-10">
+ <div className="min-w-0 flex-1">
+ <DocsContent
+ slug={selectedSlug}
+ onSelect={selectDoc}
+ onShowOverview={showOverview}
+ onOpenSearch={() => setSearchOpen(true)}
+ />
+ </div>
+ {selectedSlug && (
+ <DocsToc headings={headings} contentRef={contentRef} />
+ )}
+ </div>
</main>
- <DocsToc headings={headings} contentRef={contentRef} />
<DocsSearchModal
open={searchOpen}