Skip to content

Add an llms.txt index for the documentation (#660) #661

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
phmatray wants to merge 6 commits into
base: develop
Choose a base branch
from
Open

Add an llms.txt index for the documentation (#660) #661

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
804ad4a
Scaffold the draft PR for the llms.txt index (#660)
phmatray Aug 27, 2026
71cc290
Walk the docs website and derive public URLs
phmatray Aug 27, 2026
27dddd0
Parse the docs frontmatter into page metadata
phmatray Aug 27, 2026
de39ca6
Generate an llms.txt index from the docs frontmatter
phmatray Aug 27, 2026
86d5109
Fail the build when llms.txt is out of sync with the docs
phmatray Aug 27, 2026
7383c59
Harden the llms.txt generator against docs it does not yet contain
phmatray Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .fallout/build.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
"CreateGitHubRelease",
"DeletePackages",
"DownloadLicenses",
"GenerateLlmsTxt",
"GeneratePublicApi",
"GenerateTools",
"Install",
Expand All @@ -42,7 +43,8 @@
"Test",
"UpdateContributors",
"UpdateStargazers",
"VerifyGeneratedTools"
"VerifyGeneratedTools",
"VerifyLlmsTxt"
]
},
"Verbosity": {
Expand Down
42 changes: 36 additions & 6 deletions .github/workflows/build-skip.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,29 @@
# - Without a substitute, docs-only PRs sit BLOCKED waiting for a check that
# never reports.
#
# This workflow fires on the inverse path set (docs-only changes), runs nothing
# of substance, and reports success under the same `ubuntu-latest` status-check
# context — satisfying the protection rule without spending CI minutes on a real
# build.
# This workflow fires on the inverse path set (docs-only changes) and reports
# success under the same `ubuntu-latest` status-check context, satisfying the
# protection rule without spending CI minutes on a full build/test/pack.
#
# It is not a no-op any more. docs/llms.txt is generated from docs/website by
# `GenerateLlmsTxt`, so a docs-only PR is exactly the change that can leave it
# stale — and it is exactly the change build.yml ignores. VerifyLlmsTxt therefore
# runs here, which is the only workflow that sees these PRs. It builds the build
# project and regenerates one file; it does not run the test or pack targets.
#
# Keep the job name `ubuntu-latest` aligned with build.yml so both files produce
# a status check named `ubuntu-latest`; the workflow `name:` mirrors build.yml's
# `build` so docs-only runs appear under the same workflow in the Actions tab.

name: build

# Mirrors build.yml. This job does real work now, so rapid pushes to a docs PR
# would otherwise stack concurrent builds, which is the cost this file exists to
# avoid in the first place.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}

@dennisdoomen dennisdoomen Aug 29, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔧🤖 Same concurrency group as build.yml (both name: build) — a PR touching code + a .md file triggers both workflows, and cancel-in-progress lets one cancel the other.

cancel-in-progress: true

on:
pull_request:
branches:
Expand All @@ -37,5 +49,23 @@ jobs:
name: ubuntu-latest
runs-on: ubuntu-latest
steps:
- name: 'Skip: docs-only PR, no build needed'
run: echo "Docs-only change — ubuntu-latest validation skipped via .github/workflows/build-skip.yml."
- uses: actions/checkout@v7
with:
fetch-depth: 0
repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
ref: ${{ github.head_ref }}
- name: 'Cache: .fallout/temp, ~/.nuget/packages'
uses: actions/cache@v6
with:
path: |
.fallout/temp
~/.nuget/packages
key: ${{ runner.os }}-${{ hashFiles('**/global.json', '**/*.csproj', '**/Directory.Packages.props') }}
- name: 'Setup: .NET SDK'
uses: actions/setup-dotnet@v6
with:
global-json-file: global.json
- name: 'Restore: dotnet tools'
run: dotnet tool restore
- name: 'Run: VerifyLlmsTxt'
run: dotnet fallout VerifyLlmsTxt
4 changes: 2 additions & 2 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,5 +55,5 @@ jobs:
global-json-file: global.json
- name: 'Restore: dotnet tools'
run: dotnet tool restore
- name: 'Run: VerifyGeneratedTools, Test, Pack'
run: dotnet fallout VerifyGeneratedTools Test Pack
- name: 'Run: VerifyGeneratedTools, VerifyLlmsTxt, Test, Pack'
run: dotnet fallout VerifyGeneratedTools VerifyLlmsTxt Test Pack
2 changes: 1 addition & 1 deletion build/Build.CI.GitHubActions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
// long-lived and protected; all require the ubuntu-latest check.
OnPullRequestBranches = new[] { DevelopBranch, MainBranch, ReleaseBranchPattern, SupportBranchPattern },
OnPullRequestExcludePaths = new[] { "docs/**", ".assets/**", "**/*.md" },
InvokedTargets = new[] { nameof(VerifyGeneratedTools), nameof(ITest.Test), nameof(IPack.Pack) },
InvokedTargets = new[] { nameof(VerifyGeneratedTools), nameof(VerifyLlmsTxt), nameof(ITest.Test), nameof(IPack.Pack) },
PublishArtifacts = false)]
[GitHubActions(
"build-cross-platform",
Expand Down
Loading