Skip to content

Commit e73c5ec

Browse files
ShewartShewart
authored
Merge pull request #1 from shellui-dev/chore/repo-scaffolding
chore: scaffold ShellDocs monorepo — 6 projects, .slnx, CI, design docs
2 parents 32a1f51 + 07e1bb5 commit e73c5ec

25 files changed

Lines changed: 1873 additions & 2 deletions

‎.github/workflows/ci.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
jobs:
11+
build-test:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Setup .NET
17+
uses: actions/setup-dotnet@v4
18+
with:
19+
global-json-file: global.json
20+
21+
- name: Restore
22+
run: dotnet restore shelldocs.slnx
23+
24+
- name: Build
25+
run: dotnet build shelldocs.slnx --configuration Release --no-restore
26+
27+
- name: Test
28+
run: dotnet test shelldocs.slnx --configuration Release --no-build --verbosity normal
29+
30+
# Smoke test: verify the CLI packs cleanly as a global tool
31+
- name: Pack CLI
32+
run: dotnet pack src/ShellDocs.CLI --configuration Release --output nupkgs
33+
34+
- name: Verify CLI installs + runs
35+
run: |
36+
dotnet tool install --global --add-source ./nupkgs ShellDocs.CLI --prerelease
37+
shelldocs --help

‎.gitignore‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# .NET build output
2+
[Bb]in/
3+
[Oo]bj/
4+
[Rr]elease/
5+
[Dd]ebug/
6+
*.user
7+
*.suo
8+
*.userosscache
9+
*.sln.docstates
10+
*.dll
11+
*.pdb
12+
*.exe
13+
*.cache
14+
15+
# NuGet
16+
*.nupkg
17+
*.snupkg
18+
project.lock.json
19+
project.assets.json
20+
packages/
21+
!.nuget/packages/
22+
.nuget/
23+
24+
# Test results
25+
[Tt]est[Rr]esult*/
26+
[Cc]overage*/
27+
28+
# IDE
29+
.vs/
30+
.vscode/
31+
.idea/
32+
*.swp
33+
*.swo
34+
35+
# JetBrains Rider
36+
_ReSharper*/
37+
*.[Rr]e[Ss]harper
38+
*.DotSettings.user
39+
40+
# OS
41+
.DS_Store
42+
Thumbs.db
43+
44+
# Node (for Tailwind CLI + Shiki)
45+
node_modules/
46+
package-lock.json
47+
yarn.lock
48+
pnpm-lock.yaml
49+
50+
# ShellDocs — local build artifacts
51+
publish/
52+
dist/
53+
.shelldocs/
54+
*.shellui-classes-generated
55+
56+
# Environment
57+
.env
58+
.env.*
59+
!.env.example
60+
61+
# Logs
62+
*.log
63+
logs/

‎Directory.Build.props‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<Project>
2+
3+
<PropertyGroup>
4+
<TargetFramework>net10.0</TargetFramework>
5+
<LangVersion>latest</LangVersion>
6+
<Nullable>enable</Nullable>
7+
<ImplicitUsings>enable</ImplicitUsings>
8+
<TreatWarningsAsErrors>false</TreatWarningsAsErrors>
9+
<WarningsAsErrors>Nullable</WarningsAsErrors>
10+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
11+
<NoWarn>$(NoWarn);CS1591</NoWarn> <!-- suppress "missing XML comment" until we backfill -->
12+
</PropertyGroup>
13+
14+
<!-- Central package version pinning via Directory.Packages.props -->
15+
<PropertyGroup>
16+
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
17+
</PropertyGroup>
18+
19+
<!-- Package metadata (applies to any project with IsPackable=true) -->
20+
<PropertyGroup>
21+
<Authors>ShellUI</Authors>
22+
<Company>ShellUI</Company>
23+
<Copyright>Copyright © 2026 ShellUI</Copyright>
24+
<PackageLicenseExpression>MIT</PackageLicenseExpression>
25+
<PackageProjectUrl>https://github.com/shellui-dev/shelldocs</PackageProjectUrl>
26+
<RepositoryUrl>https://github.com/shellui-dev/shelldocs</RepositoryUrl>
27+
<RepositoryType>git</RepositoryType>
28+
<PackageTags>blazor;docs;documentation;framework;shellui;shadcn;fumadocs;tailwind</PackageTags>
29+
<PackageReadmeFile>README.md</PackageReadmeFile>
30+
<IncludeSymbols>true</IncludeSymbols>
31+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
32+
<PublishRepositoryUrl>true</PublishRepositoryUrl>
33+
<EmbedUntrackedSources>true</EmbedUntrackedSources>
34+
</PropertyGroup>
35+
36+
<!-- Default: nothing is packable unless the project opts in -->
37+
<PropertyGroup>
38+
<IsPackable>false</IsPackable>
39+
</PropertyGroup>
40+
41+
<!-- Include README in packages that opt in -->
42+
<ItemGroup Condition="'$(IsPackable)' == 'true'">
43+
<None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="\" />
44+
</ItemGroup>
45+
46+
</Project>

‎Directory.Packages.props‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<Project>
2+
3+
<ItemGroup>
4+
<!-- Framework -->
5+
<PackageVersion Include="Microsoft.AspNetCore.Components.Web" Version="10.0.0" />
6+
<PackageVersion Include="Microsoft.AspNetCore.Components.WebAssembly" Version="10.0.0" />
7+
<PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.0" />
8+
<PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
9+
<PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
10+
11+
<!-- Markdown pipeline -->
12+
<PackageVersion Include="Markdig" Version="0.38.0" />
13+
<PackageVersion Include="YamlDotNet" Version="16.2.1" />
14+
15+
<!-- CLI -->
16+
<PackageVersion Include="System.CommandLine" Version="2.0.0-beta5.25306.1" />
17+
<PackageVersion Include="Spectre.Console" Version="0.49.1" />
18+
19+
<!-- ShellUI (base primitives — added in feat/components-shell once ShellUI is published to NuGet)
20+
<PackageVersion Include="ShellUI.Components" Version="0.4.0" />
21+
-->
22+
23+
<!-- Test stack -->
24+
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
25+
<PackageVersion Include="xunit" Version="2.9.2" />
26+
<PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
27+
<PackageVersion Include="coverlet.collector" Version="6.0.2" />
28+
</ItemGroup>
29+
30+
</Project>

‎LICENSE‎

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

‎README.md‎

Lines changed: 92 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,92 @@
1-
# shelldocs
2-
shelldocs framework for writing docs using shellui
1+
# ShellDocs
2+
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.
4+
5+
> Status: **`0.1.0-alpha` in progress.** Not yet published to NuGet. See [ROADMAP](docs/ROADMAP.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
21+
22+
## Quick start
23+
24+
```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
31+
32+
# Initialize the docs site
33+
shelldocs init
34+
35+
# Author content in Markdown
36+
shelldocs new page introduction
37+
38+
# Develop with hot-reload
39+
shelldocs dev
40+
41+
# Ship it
42+
shelldocs build
43+
```
44+
45+
## Coexists with ShellUI (and any Blazor UI library)
46+
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.
48+
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.
56+
57+
## Package family
58+
59+
| Package | Purpose |
60+
|---|---|
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
74+
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
78+
79+
Once we ship `0.2.0-alpha`, official docs will live at **[shelldocs.dev](https://shelldocs.dev)** (dogfooded on ShellDocs itself).
80+
81+
## Related projects
82+
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
85+
86+
## Contributing
87+
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`.
89+
90+
## License
91+
92+
[MIT](LICENSE) — do whatever you want, no warranty.

0 commit comments

Comments
 (0)