chore: scaffold ShellDocs monorepo — 6 projects, .slnx, CI, design docs

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+
+      - name: Restore
+        run: dotnet restore shelldocs.slnx
+
+      - name: Build
+        run: dotnet build shelldocs.slnx --configuration Release --no-restore
+
+      - name: Test
+        run: dotnet test shelldocs.slnx --configuration Release --no-build --verbosity normal
+
+      # Smoke test: verify the CLI packs cleanly as a global tool
+      - name: Pack CLI
+        run: dotnet pack src/ShellDocs.CLI --configuration Release --output nupkgs
+
+      - name: Verify CLI installs + runs
+        run: |
+          dotnet tool install --global --add-source ./nupkgs ShellDocs.CLI --prerelease
+          shelldocs --help

.gitignore

@@ -0,0 +1,63 @@
+# .NET build output
+[Bb]in/
+[Oo]bj/
+[Rr]elease/
+[Dd]ebug/
+*.user
+*.suo
+*.userosscache
+*.sln.docstates
+*.dll
+*.pdb
+*.exe
+*.cache
+
+# NuGet
+*.nupkg
+*.snupkg
+project.lock.json
+project.assets.json
+packages/
+!.nuget/packages/
+.nuget/
+
+# Test results
+[Tt]est[Rr]esult*/
+[Cc]overage*/
+
+# IDE
+.vs/
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# JetBrains Rider
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.DotSettings.user
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node (for Tailwind CLI + Shiki)
+node_modules/
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# ShellDocs — local build artifacts
+publish/
+dist/
+.shelldocs/
+*.shellui-classes-generated
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log
+logs/

Directory.Build.props

@@ -0,0 +1,46 @@
+<Project>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
+    <WarningsAsErrors>Nullable</WarningsAsErrors>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);CS1591</NoWarn> <!-- suppress "missing XML comment" until we backfill -->
+  </PropertyGroup>
+
+  <!-- Central package version pinning via Directory.Packages.props -->
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <!-- Package metadata (applies to any project with IsPackable=true) -->
+  <PropertyGroup>
+    <Authors>ShellUI</Authors>
+    <Company>ShellUI</Company>
+    <Copyright>Copyright © 2026 ShellUI</Copyright>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageProjectUrl>https://github.com/shellui-dev/shelldocs</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/shellui-dev/shelldocs</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageTags>blazor;docs;documentation;framework;shellui;shadcn;fumadocs;tailwind</PackageTags>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <IncludeSymbols>true</IncludeSymbols>
+    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+    <PublishRepositoryUrl>true</PublishRepositoryUrl>
+    <EmbedUntrackedSources>true</EmbedUntrackedSources>
+  </PropertyGroup>
+
+  <!-- Default: nothing is packable unless the project opts in -->
+  <PropertyGroup>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <!-- Include README in packages that opt in -->
+  <ItemGroup Condition="'$(IsPackable)' == 'true'">
+    <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
+</Project>

Directory.Packages.props

@@ -0,0 +1,30 @@
+<Project>
+
+  <ItemGroup>
+    <!-- Framework -->
+    <PackageVersion Include="Microsoft.AspNetCore.Components.Web" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.Components.WebAssembly" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
+
+    <!-- Markdown pipeline -->
+    <PackageVersion Include="Markdig" Version="0.38.0" />
+    <PackageVersion Include="YamlDotNet" Version="16.2.1" />
+
+    <!-- CLI -->
+    <PackageVersion Include="System.CommandLine" Version="2.0.0-beta5.25306.1" />
+    <PackageVersion Include="Spectre.Console" Version="0.49.1" />
+
+    <!-- ShellUI (base primitives — added in feat/components-shell once ShellUI is published to NuGet)
+         <PackageVersion Include="ShellUI.Components" Version="0.4.0" />
+    -->
+
+    <!-- Test stack -->
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageVersion Include="xunit" Version="2.9.2" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.2" />
+  </ItemGroup>
+
+</Project>

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShellUI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,92 @@
-# shelldocs
-shelldocs framework for writing docs using shellui
+# ShellDocs
+
+**The docs framework for .NET.** Beautiful, animated, Cmd+K-searchable documentation sites, powered by Blazor and Tailwind. Compose with ShellUI (or any Blazor component library) — like fumadocs composes with shadcn/ui.
+
+> Status: **`0.1.0-alpha` in progress.** Not yet published to NuGet. See [ROADMAP](docs/ROADMAP.md).
+
+## Why ShellDocs
+
+Every .NET UI library ends up hand-rolling their own docs site. MudBlazor, Radzen, AvaloniaUI — each spent months rebuilding a sidebar, a search box, a code block, a theme toggle, from scratch. None of it is reusable.
+
+ShellDocs is the "just use this" answer. It's the docs framework for the whole .NET ecosystem.
+
+- **Markdown authoring** with YAML frontmatter, inline Razor tags, and live component previews (`` ```razor:preview ``)
+- **File-based routing** — drop a `.md` in `content/` and it's a page
+- **Cmd+K search** with a build-time client-side index — no backend needed
+- **Blazor-native** — components render as real Razor, not iframes, not screenshots
+- **Composable with any Blazor component library** — ShellUI, MudBlazor, Radzen, your own
+- **Tailwind CSS v4** — same aesthetic as ShellUI + shadcn, same theme tokens for interop
+- **Animated** — page transitions, sidebar collapses, scroll-spy, `prefers-reduced-motion` aware
+- **Static site output** — deploy to GitHub Pages, Vercel, Netlify, Cloudflare, anywhere
+
+## Quick start
+
+```bash
+# Create a new Blazor WASM app
+dotnet new blazorwasm -n MyDocs
+cd MyDocs
+
+# Install the ShellDocs CLI
+dotnet tool install -g ShellDocs.CLI
+
+# Initialize the docs site
+shelldocs init
+
+# Author content in Markdown
+shelldocs new page introduction
+
+# Develop with hot-reload
+shelldocs dev
+
+# Ship it
+shelldocs build
+```
+
+## Coexists with ShellUI (and any Blazor UI library)
+
+ShellDocs uses the same Tailwind v4 setup and CSS variable contract as ShellUI. Both libraries share the same theme tokens (`--background`, `--foreground`, `--primary`, `--border`, `--radius`, etc.), so you can drop them into the same page and they compose seamlessly — the fumadocs + shadcn pattern, ported to .NET.
+
+```razor
+@* Your docs page — ShellUI components inline in Markdown *@
+<Button Variant="ButtonVariant.Default">A ShellUI button</Button>
+<Callout Type="Tip">A ShellDocs callout</Callout>
+```
+
+Under the hood ShellDocs takes a hard dependency on `ShellUI.Components` for base primitives (`Button`, `Dialog`, `Command`, `Sidebar`, etc.). Zero style clash.
+
+## Package family
+
+| Package | Purpose |
+|---|---|
+| [`ShellDocs.CLI`](src/ShellDocs.CLI) | Global tool — `shelldocs init`, `shelldocs new`, `shelldocs dev`, `shelldocs build` |
+| [`ShellDocs.Components`](src/ShellDocs.Components) | RCL — `DocsLayout`, `DocsSidebar`, `CodeBlock`, `SearchDialog`, `TableOfContents`, etc. |
+| [`ShellDocs.Markdown`](src/ShellDocs.Markdown) | Markdig pipeline — frontmatter, `razor:preview` fences, inline Razor tags |
+| [`ShellDocs.Core`](src/ShellDocs.Core) | Navigation graph, search index model, routing helpers. Blazor-agnostic. |
+| [`ShellDocs.Templates`](src/ShellDocs.Templates) | Content used by `ShellDocs.CLI` scaffolding |
+
+Optional / v2:
+
+- **`ShellDocs.Xml`** — extract `<TypeTable>` from XML doc comments
+- **`ShellDocs.Themes.Fuma`**, **`ShellDocs.Themes.Nextra`** — theme presets
+- **`ShellDocs.OpenApi`** — OpenAPI spec → API reference pages
+
+## Documentation
+
+- [Design](docs/DESIGN.md) — what ShellDocs is, positioning, primitives, ecosystem story
+- [Roadmap](docs/ROADMAP.md) — branch-by-branch implementation plan
+- [Architecture](docs/ARCHITECTURE.md) — technical architecture: package boundaries, service registration, markdown pipeline, navigation graph, search index
+
+Once we ship `0.2.0-alpha`, official docs will live at **[shelldocs.dev](https://shelldocs.dev)** (dogfooded on ShellDocs itself).
+
+## Related projects
+
+- [ShellUI](https://github.com/shellui-dev/shellui) — the Blazor component library ShellDocs is built with
+- [shellui.dev](https://github.com/shellui-dev/shellui.dev) *(coming soon)* — ShellUI's own docs site, built with ShellDocs
+
+## Contributing
+
+`0.1.0-alpha` is scaffolding-first — architecture and API surface are still moving. Once we hit `0.2.0-alpha`, we'll open up contributions with a proper `CONTRIBUTING.md`.
+
+## License
+
+[MIT](LICENSE) — do whatever you want, no warranty.