You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`ShellDocs.Tokens`| Shared CSS variable definitions — the palette + spacing scale that both ShellDocs and ShellUI-in-docs consume. Single source of truth for `--background`, `--foreground`, `--primary`, `--radius`, etc. |
|`ShellDocs.Xml`| v2 — extract `<TypeTable>` from XML doc comments |
@@ -38,17 +39,17 @@ Each branch below annotates which package it touches. Multi-package branches cal
38
39
39
40
Goal: a consumer can `shelldocs init` an empty Blazor WASM project and get a working docs site with sidebar, header, code blocks, and one theme.
40
41
41
-
### `chore/repo-scaffolding`
42
+
### ✅ `chore/repo-scaffolding` — shipped
42
43
Bootstrap the monorepo.
43
44
44
-
-`.sln` with the six package projects (`ShellDocs.Core`, `ShellDocs.Markdown`, `ShellDocs.Components`, `ShellDocs.CLI`, `ShellDocs.Templates`, plus `ShellDocs.Tests`)
45
+
-`.slnx` (.NET 10 XML solution format) with all package projects + tests
45
46
-`.csproj` files with correct `TargetFramework`, `IsPackable`, `PackageId`
46
47
-`.gitignore`, `Directory.Build.props`, `Directory.Packages.props` for central package management
47
48
-`.github/workflows/ci.yml` — build + test on every push
48
49
-`.github/workflows/release.yml` — pack + push to NuGet on tag
49
50
- Nothing shipped; groundwork only
50
51
51
-
### `feat/core-navigation-graph`
52
+
### ✅ `feat/core-navigation-graph` — shipped
52
53
Ships to `ShellDocs.Core`.
53
54
54
55
-`NavigationGraph` — tree of `NavigationNode { Url, Title, Description, Category, Order, Headings, Path }`
-`DocsHeader` — logo, primary nav with hover mega-menu (icon cards), search-button placeholder, theme toggle, GitHub link, hamburger for mobile
76
+
-`DocsSidebar` — grouped nav from navigation graph, collapsible sections (fumadocs pattern — closed by default, active-path auto-open), lucide-style icons per section/page, package selector (ShellDocs · Markdown · Core · CLI · Components), footer bar with GitHub + theme toggle
76
77
-`MarkdownContent` — renders a doc page from a `.md` path via `MarkdownRenderer`
77
-
- One theme preset baked in (`Shadcn`)
78
-
- No search, no TOC, no code highlighting yet — those come in later branches
78
+
-`TableOfContents` — right-rail nav (h2/h3), scroll-tracked via multi-active headings so the thumb slides smoothly, SVG-mask + coloured thumb pattern lifted from fumadocs' `ClerkTOCItems`
-`MobileNavState` service + fixed drawer + backdrop + auto-close on route change
81
+
- Prism.js syntax highlighting (via CDN for now — Shiki lands in the next branch)
82
+
- Neutral fumadocs-shaped palette (`--background`, `--foreground`, `--primary`, `--muted`, `--accent`, `--border`) — will move to `ShellDocs.Tokens` in the next branch
83
+
84
+
### `feat/design-tokens` — **next**
85
+
Ships to new package `ShellDocs.Tokens`.
86
+
87
+
Extracts the palette + scale from `ShellDocs.Components/wwwroot/shelldocs-theme.css` into its own package so ShellUI (and any third-party consumer) can depend on the *tokens* without pulling in the whole components RCL.
88
+
89
+
- New `ShellDocs.Tokens` project — RCL that ships a single `wwwroot/tokens.css` with `:root` + `:root.dark` variable definitions
90
+
-`ShellDocs.Components` and `ShellDocs.Preview` update their `App.razor` link to `_content/ShellDocs.Tokens/tokens.css` and remove the inline theme file
91
+
- Add a `tokens-full.css` variant for consumers who want the extended set (semantic + chart colors), and a `tokens-base.css` for consumers who only want the core palette
92
+
- Document the token contract in `docs/TOKENS.md`: which names are stable, which are internal, and how to override
93
+
-**ShellUI integration path (Tailwind install):** ShellUI's Tailwind config reads the same `--primary`, `--background`, `--border` etc. — nothing changes on their side. Consumer just references `tokens.css` and both design systems light up together.
94
+
-**ShellUI integration path (NuGet install):** ShellUI's RCL detects `ShellDocs.Tokens` at runtime and skips emitting its own token file. Deferred to Phase 3 — needs a small opt-in flag on `AddShellUI()`.
95
+
- Unit tests: token file emits, dark-mode class toggling, no duplicate declarations across bundles
79
96
80
97
### `feat/codeblock-shiki`
81
98
Ships to `ShellDocs.Components`.
@@ -303,6 +320,14 @@ ShellDocs depends on `ShellUI.Components` for base primitives:
303
320
304
321
**Locked ShellUI version:** ShellDocs targets `ShellUI.Components >= 0.5.0` (the version that ships `feat/data-selection-suite` — CommandPalette is required). Bumps require a ShellDocs major/minor.
305
322
323
+
### Install path — Tailwind-first, NuGet later
324
+
325
+
Mirrors how shadcn interops with fumadocs: shared CSS variables on `:root`, both design systems read them, one visual language.
326
+
327
+
-**Phase 1–2 (now):** ShellUI ships as a Tailwind consumer. Doc site owners install ShellUI the same way they would in any Blazor app — via `shellui add card` etc. — and the components read the same `--primary`, `--muted`, `--border` tokens that ShellDocs emits. Zero interop work; a `<Card>` written mid-markdown just picks up the ShellDocs palette. `ShellDocs.Tokens` (next branch) formalizes the contract so both packages point at the same source of truth.
328
+
-**Phase 3+ (`feat/shellui-nuget-interop`):** teach the ShellUI NuGet RCL to defer to `ShellDocs.Tokens` when it's on the classpath, so shipping both packages doesn't double-emit `:root` blocks. Small change — an `AddShellUI(o => o.UseSharedTokens())` opt-in. Deferred because it's not blocking for real docs sites — Tailwind consumers get 90% of the value today, and the NuGet story only matters for pure-server projects that don't run Tailwind.
329
+
-**Not doing:** shipping a "ShellUI-NuGet-only" install story for now. It'd double the QA surface for zero customer wins on day one. Revisit when a real consumer asks.
"The docs framework we wanted for .NET. Markdown-first, Razor-native, Cmd+K searchable, deploys anywhere. Here's what shipped and what's next on the roadmap.",
"The story of every fumadocs-inspired scroll spy we shipped, why they broke on Blazor Server, and the 50-line version we ended up with. A lesson in doing less.",
"How ShellDocs decides sidebar ordering, breadcrumbs, and prev/next navigation from a single YAML block. Plus: the meta.json escape hatch for when you need it.",
"A short walkthrough of how <Button /> mid-markdown becomes a real Blazor component at render time. Includes the parsing rules and why we chose them.",
"Why round-tripping every scroll event through SignalR is a bad idea, and the pattern we use to keep Blazor out of hot animation loops. Applies to any Blazor Server app.",
new("How shellui.dev is being rebuilt on ShellDocs",
61
+
"A dogfood tour: the ShellUI docs site is moving from custom Blazor pages to ShellDocs' primitives. Screenshots, migration notes, and every rough edge we hit.",
0 commit comments