Skip to content

Commit 1c88058

Browse files
ShewartShewart
committed
docs: update README.md to reflect changes in ShellDocs 0.1.2-alpha, enhancing clarity on features, installation steps, and documentation structure
1 parent b7cc15c commit 1c88058

1 file changed

Lines changed: 41 additions & 61 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,72 @@
11
# ShellDocs
22

3-
**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.
3+
**The docs framework for .NET.** Beautiful, animated, `Cmd+K`-searchable documentation sites. Powered by Blazor, styled with Tailwind-shaped design tokens, composable with any Blazor component library. The fumadocs / shadcn pattern, ported to .NET.
44

5-
> Status: **`0.1.0-alpha`** — first public release. See [CHANGELOG](CHANGELOG.md) and [ROADMAP](docs/ROADMAP.md). Publish steps live in [docs/RELEASING.md](docs/RELEASING.md).
6-
7-
## Why ShellDocs
8-
9-
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.
10-
11-
ShellDocs is the "just use this" answer. It's the docs framework for the whole .NET ecosystem.
12-
13-
- **Markdown authoring** with YAML frontmatter, inline Razor tags, and live component previews (`` ```razor:preview ``)
14-
- **File-based routing** — drop a `.md` in `content/` and it's a page
15-
- **Cmd+K search** with a build-time client-side index — no backend needed
16-
- **Blazor-native** — components render as real Razor, not iframes, not screenshots
17-
- **Composable with any Blazor component library** — ShellUI, MudBlazor, Radzen, your own
18-
- **Tailwind CSS v4** — same aesthetic as ShellUI + shadcn, same theme tokens for interop
19-
- **Animated** — page transitions, sidebar collapses, scroll-spy, `prefers-reduced-motion` aware
20-
- **Static site output** — deploy to GitHub Pages, Vercel, Netlify, Cloudflare, anywhere
5+
> `0.1.2-alpha` on nuget.org. See [CHANGELOG](CHANGELOG.md) and [ROADMAP](docs/ROADMAP.md). Docs at [shelldocs.dev](https://shelldocs.dev).
216
227
## Quick start
238

249
```bash
25-
# Create a new Blazor WASM app
26-
dotnet new blazorwasm -n MyDocs
27-
cd MyDocs
28-
29-
# Install the ShellDocs CLI
30-
dotnet tool install -g ShellDocs.CLI
10+
# Install the CLI (once)
11+
dotnet tool install -g ShellDocs.CLI --prerelease
3112

32-
# Initialize the docs site
33-
shelldocs init
13+
# Scaffold a site (creates docs/MyDocs.Docs/)
14+
shelldocs init MyDocs
3415

35-
# Author content in Markdown
36-
shelldocs new page introduction
16+
# Add pages
17+
shelldocs add component Button
18+
shelldocs add guide getting-started
3719

38-
# Develop with hot-reload
20+
# Run with hot reload
21+
cd docs/MyDocs.Docs
3922
shelldocs dev
4023

41-
# Ship it
42-
shelldocs build
24+
# Ship
25+
shelldocs build --output publish
4326
```
4427

45-
## Coexists with ShellUI (and any Blazor UI library)
28+
That's a working docs site. See [shelldocs.dev/docs/getting-started/quick-start](https://shelldocs.dev/docs/getting-started/quick-start) for the walkthrough.
4629

47-
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.
30+
## What you get
4831

49-
```razor
50-
@* Your docs page — ShellUI components inline in Markdown *@
51-
<Button Variant="ButtonVariant.Default">A ShellUI button</Button>
52-
<Callout Type="Tip">A ShellDocs callout</Callout>
53-
```
54-
55-
Under the hood ShellDocs takes a hard dependency on `ShellUI.Components` for base primitives (`Button`, `Dialog`, `Command`, `Sidebar`, etc.). Zero style clash.
32+
- **Markdown-first authoring.** YAML frontmatter, fenced code blocks with Shiki, live-rendered `razor:preview` examples, inline Razor component tags mid-prose.
33+
- **Auto-wired navigation.** File-based routing. Drop a `.md` in `content/docs/` and it becomes a page. Sidebar, breadcrumb, prev/next, TOC — all derived from the tree.
34+
- **`Cmd+K` search.** Client-side substring scoring against title, description, section, and body text. Snippet extraction for body-only hits. Zero backend, zero external service.
35+
- **Blazor-native.** Components render as real Razor. Full JS interop, hot reload, all the tooling you already have.
36+
- **Composable.** Bring your own component library (ShellUI, MudBlazor, Radzen, hand-rolled). One-line assembly-scan registration:
37+
```csharp
38+
o.RegisterComponentsFromAssembly<MyLib.Button>();
39+
```
40+
- **Static site output.** `shelldocs build` produces static HTML ready for GitHub Pages, Vercel, Netlify, Cloudflare, anywhere. Base-href rewrite + SPA 404 fallback included.
5641

5742
## Package family
5843

5944
| Package | Purpose |
6045
|---|---|
61-
| [`ShellDocs.CLI`](src/ShellDocs.CLI) | Global tool — `shelldocs init`, `shelldocs new`, `shelldocs dev`, `shelldocs build` |
62-
| [`ShellDocs.Components`](src/ShellDocs.Components) | RCL — `DocsLayout`, `DocsSidebar`, `CodeBlock`, `SearchDialog`, `TableOfContents`, etc. |
63-
| [`ShellDocs.Markdown`](src/ShellDocs.Markdown) | Markdig pipeline — frontmatter, `razor:preview` fences, inline Razor tags |
64-
| [`ShellDocs.Core`](src/ShellDocs.Core) | Navigation graph, search index model, routing helpers. Blazor-agnostic. |
65-
| [`ShellDocs.Templates`](src/ShellDocs.Templates) | Content used by `ShellDocs.CLI` scaffolding |
66-
67-
Optional / v2:
68-
69-
- **`ShellDocs.Xml`** — extract `<TypeTable>` from XML doc comments
70-
- **`ShellDocs.Themes.Fuma`**, **`ShellDocs.Themes.Nextra`** — theme presets
71-
- **`ShellDocs.OpenApi`** — OpenAPI spec → API reference pages
72-
73-
## Documentation
46+
| [`ShellDocs.CLI`](src/ShellDocs.CLI) | Global tool. `shelldocs init`, `add`, `dev`, `build` |
47+
| [`ShellDocs.Components`](src/ShellDocs.Components) | RCL. Chrome (layout, sidebar, header, search) + content primitives (Callout, Card, Steps, CodeGroup, FileTree, TypeTable, ComponentPreview) |
48+
| [`ShellDocs.Markdown`](src/ShellDocs.Markdown) | Markdig pipeline. Frontmatter parser, `razor:preview` fence extractor, inline Razor tag extractor, per-property type coercion |
49+
| [`ShellDocs.Core`](src/ShellDocs.Core) | Navigation graph, search index, plain-text extraction. No UI |
50+
| [`ShellDocs.Tokens`](src/ShellDocs.Tokens) | Design-system CSS variables. shadcn-compatible names for interop with ShellUI and Tailwind-shaped design systems |
51+
| [`ShellDocs.Templates`](src/ShellDocs.Templates) | Starter markdown + Program.cs snippets emitted by `shelldocs init` |
7452

75-
- [Design](docs/DESIGN.md) — what ShellDocs is, positioning, primitives, ecosystem story
76-
- [Roadmap](docs/ROADMAP.md) — branch-by-branch implementation plan
77-
- [Architecture](docs/ARCHITECTURE.md) — technical architecture: package boundaries, service registration, markdown pipeline, navigation graph, search index
53+
## Docs
7854

79-
Once we ship `0.2.0-alpha`, official docs will live at **[shelldocs.dev](https://shelldocs.dev)** (dogfooded on ShellDocs itself).
55+
- [shelldocs.dev](https://shelldocs.dev) : full documentation site (built with ShellDocs itself)
56+
- [docs/DESIGN.md](docs/DESIGN.md) : product positioning, primitive inventory, ecosystem story
57+
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) : package boundaries, service registration, markdown pipeline, navigation graph, search
58+
- [docs/ROADMAP.md](docs/ROADMAP.md) : branch-by-branch delivery plan
59+
- [docs/RELEASING.md](docs/RELEASING.md) : how a maintainer cuts a NuGet release (Trusted Publishing)
8060

81-
## Related projects
61+
## Related
8262

83-
- [ShellUI](https://github.com/shellui-dev/shellui) — the Blazor component library ShellDocs is built with
84-
- [shellui.dev](https://github.com/shellui-dev/shellui.dev) *(coming soon)* — ShellUI's own docs site, built with ShellDocs
63+
- [shellui-dev/shellui](https://github.com/shellui-dev/shellui) : the Blazor component library ShellDocs' authors are building alongside
64+
- [shellui-dev/shelldocs-docs](https://github.com/shellui-dev/shelldocs-docs) : source for [shelldocs.dev](https://shelldocs.dev), consuming ShellDocs from NuGet like any other user
8565

8666
## Contributing
8767

88-
`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`.
68+
The alpha is API-fluid : we're taking freedom to break minor versions until `1.0`. Bug reports and dogfood-driven fixes welcome via issues. A proper `CONTRIBUTING.md` lands with the `0.2.0-alpha` cut.
8969

9070
## License
9171

92-
[MIT](LICENSE) — do whatever you want, no warranty.
72+
[MIT](LICENSE). Do whatever you want, no warranty.

0 commit comments

Comments
 (0)