Merge pull request #1 from shellui-dev/feat/shelldocs-0.1.17-llms

feat: ShellDocs 0.1.17 with llms.txt for AI agents

Author: Shewart

.github/workflows/deploy-pages.yml

@@ -58,7 +58,7 @@ jobs:
       # use. Prevents a floating latest-prerelease install from silently
       # shifting the prerender behaviour under our feet mid-release-cycle.
       - name: Install shelldocs CLI
-        run: dotnet tool install -g ShellDocs.CLI --version 0.1.15-alpha
+        run: dotnet tool install -g ShellDocs.CLI --version 0.1.17-alpha
 
       # Restore explicitly so the `shelldocs build`'s embedded `dotnet
       # publish` doesn't spend the first run downloading every package

Components/App.razor

@@ -12,11 +12,6 @@
     <link rel="stylesheet" href="_content/ShellDocs.Tokens/tokens.css" />
     <link rel="stylesheet" href="_content/ShellDocs.Components/shelldocs-theme.css" />
     <link rel="stylesheet" href="ShellDocs.Site.styles.css" />
-    @* ShellDocs 0.1.15 scopes this rule so it never matches, and an inline LogoSvg
-       with no width of its own renders 0px wide. Remove once that is fixed upstream. *@
-    <style>
-        .brand-logo-svg > svg { height: 100%; width: auto; display: block; }
-    </style>
     <script>
         (function () {
             var saved = null;

Components/Pages/Home.razor

@@ -46,9 +46,6 @@
 
 <SiteFooter />
 
-@* HomeLayout has no search dialog of its own; this one makes Ctrl+K and the bento's search panel work here. *@
-<SearchDialog />
-
 <style>
     .site-home {
         max-width: 68rem;

Llms/agent-rules.md

@@ -0,0 +1,11 @@
+## Rules for AI agents
+
+Read these before building or changing a ShellDocs site.
+
+1. **Install with the CLI.** `dotnet tool install -g ShellDocs.CLI --prerelease`, then `shelldocs init` for a new site or in an existing Blazor Web App. Keep the `ShellDocs.*` package versions and the CLI version the same.
+2. **Pages are Markdown files** in `content/docs/`, with `title` and `description` frontmatter. Each folder's `meta.json` sets the sidebar order and must list every page. `shelldocs add page|guide|component <name>` scaffolds one. New pages and `meta.json` edits need a restart of the running site.
+3. **Use ShellDocs' components in Markdown; don't write HTML look-alikes.** `<Callout>`, `<Tabs>` / `<Tab>`, `<Steps>` / `<Step>`, `<CardGrid>` / `<Card>` / `<LinkCard>`, `<CodeGroup>`, `<FileTree>`, `<TypeTable>` / `<TypeRow>` and `<AutoTypeTable>`. When a site's own library has a component of the same name, the `Docs` prefix (`<DocsCallout>`) still reaches the built-in.
+4. **Live examples:** a ```` ```razor:preview ```` fence, `<ComponentPreview>`, or `<DemoPreview Component="X" />` for a `.razor` file under `DemoSourceRoot`. A `razor:preview` body is Razor, not Markdown: use `<code>` and `<strong>`, not backticks and `**`. Components used in Markdown must be registered with `RegisterComponent<T>()` or `RegisterComponentsFromAssembly<T>()`.
+5. **Attribute values on tags in Markdown are plain text.** They aren't Markdown and HTML entities aren't decoded. There is no escape for the quote character, so switch between single and double quotes.
+6. **Configuration lives in `AddShellDocs(o => ...)` in `Program.cs`:** site details, navigation, packages, versions, redirects, previews and `EnableLlmsTxt`.
+7. **Static sites come from `shelldocs build`.** Don't edit the `publish/` output by hand, and don't add `--spa-fallback` unless the host needs it: it replaces the not-found page with the home page.

Program.cs

@@ -23,6 +23,15 @@
     o.RegisterComponentsFromAssembly<App>("ShellDocs.Site.Components.Demos");
     o.DemoSourceRoot = Path.Combine(builder.Environment.ContentRootPath, "Components", "Demos");
 
+    // /llms.txt, every page as Markdown at its URL + ".md", agent instruction
+    // files and the page actions menu by the title.
+    o.EnableLlmsTxt(l =>
+    {
+        l.Summary = "ShellDocs is a docs framework for .NET: Markdown pages, live Blazor component previews, search and a static export, in a Blazor Web App.";
+        l.RulesFile = "Llms/agent-rules.md";
+        l.InstallCommandPattern = @"(?m)(?<=^[ \t]*)dotnet (?:tool install -g ShellDocs\.CLI|add package ShellDocs\.\w+)[^\r\n]*";
+    });
+
     // Top nav: three tabs. Package-specific navigation lives entirely in the
     // sidebar's package selector, not up here.
     o.AddNavLink("Documentation", "/docs/introduction");

README.md

@@ -58,7 +58,7 @@ content/
       configuration.md
     authoring/          frontmatter, code fences, razor:preview, inline tags, navigation
     components/         one page per content primitive
-    guides/             component libraries, versioning, redirects, search, not-found, deployment
+    guides/             component libraries, versioning, redirects, search, llms.txt, not-found, deployment
     cli/                init, add, dev, build
     theming.md
     packages/           one overview per NuGet package
@@ -68,6 +68,8 @@ wwwroot/
   demos/                static pages shown with <IframePreview>
   cli-replay.js         the terminal replay on the home page
   copy-button.js        copy buttons marked with data-copy
+Llms/
+  agent-rules.md        rules for AI agents, shown in /llms.txt and the agent files
 Components/
   Demos/                demo components shown with <DemoPreview>
   Home/                 the animated feature bento on the home page
@@ -76,7 +78,7 @@ Components/
 
 ## Framework version
 
-The site references `ShellDocs.* 0.1.15-alpha`. On a new release, bump the four package versions in `ShellDocs.Site.csproj` and the CLI version pinned in `.github/workflows/deploy-pages.yml` together.
+The site references `ShellDocs.* 0.1.17-alpha`. On a new release, bump the four package versions in `ShellDocs.Site.csproj` and the CLI version pinned in `.github/workflows/deploy-pages.yml` together.
 
 ## License
 

ShellDocs.Site.csproj

@@ -19,10 +19,10 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="ShellDocs.Components" Version="0.1.15-alpha" />
-    <PackageReference Include="ShellDocs.Core"       Version="0.1.15-alpha" />
-    <PackageReference Include="ShellDocs.Markdown"   Version="0.1.15-alpha" />
-    <PackageReference Include="ShellDocs.Tokens"     Version="0.1.15-alpha" />
+    <PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
+    <PackageReference Include="ShellDocs.Core"       Version="0.1.17-alpha" />
+    <PackageReference Include="ShellDocs.Markdown"   Version="0.1.17-alpha" />
+    <PackageReference Include="ShellDocs.Tokens"     Version="0.1.17-alpha" />
   </ItemGroup>
 
   <ItemGroup>
@@ -32,6 +32,8 @@
     <Content Update="content/**/meta.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
     <!-- DemoPreview reads these at runtime; the Razor SDK drops .razor files from publish otherwise. -->
     <None Include="Components/Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
+    <!-- EnableLlmsTxt reads the rules file at runtime, from the output folder and from the export's publish. -->
+    <None Update="Llms/agent-rules.md" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
   </ItemGroup>
 
 </Project>

content/docs/authoring/fenced-code.md

@@ -1,6 +1,6 @@
 ---
 title: Fenced code
-description: Regular code fences : language detection, copy button, Shiki syntax highlighting.
+description: "Regular code fences: language detection, copy button, Shiki syntax highlighting."
 order: 2
 ---
 
@@ -109,7 +109,7 @@ dotnet add package ShellDocs.Components --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.15-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
 ```
 
 </CodeTab>

content/docs/authoring/razor-preview.md

@@ -24,7 +24,13 @@ This renders as a real Callout component.
 </Callout>
 ```
 
-The tags must be components registered with ShellDocs : the built-in primitives, or [your own](/docs/guides/component-libraries).
+The tags can be components registered with ShellDocs : the built-in primitives, or [your own](/docs/guides/component-libraries). A fence of plain HTML renders live too:
+
+```razor:preview
+<p style="margin:0">A fence with <strong>only HTML</strong> and no component.</p>
+```
+
+A fence with no tags at all stays a code block, and a warning is logged. Before `0.1.17-alpha` an HTML-only fence also rendered as a code block.
 
 ## The body is Razor, not markdown
 

content/docs/cli/build.md

@@ -48,6 +48,9 @@ Requests a URL that doesn't exist and saves the site's not-found view as `404.ht
 <Step Title="Copies the search index">
 Saves the app's search index as `_shelldocs/search.json`, which is what makes search work without a server.
 </Step>
+<Step Title="Writes the llms.txt files">
+On a site that calls `EnableLlmsTxt`, writes `llms.txt`, `llms-full.txt`, every page's `.md` and the agent files. Their links use `--site-url`, then `SiteUrl`. See [AI agents (llms.txt)](/docs/guides/llms-txt).
+</Step>
 <Step Title="Copies the assets">
 Merges the published `wwwroot` into the output: framework scripts, `shelldocs.js`, stylesheets, your own static files. Prerendered pages are never overwritten.
 </Step>