From c77fa17ac2dfeca061b09abddf1363a1fc5b44f5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 22:12:08 +0000 Subject: [PATCH 1/4] Initial plan From b4fd4de6eb614eb2fabb6379fc80dcfe2dd427c7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 22:13:48 +0000 Subject: [PATCH 2/4] Add Copilot instructions for the repository Co-authored-by: TimHess <3947063+TimHess@users.noreply.github.com> --- .github/copilot-instructions.md | 171 ++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..6d22d77e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,171 @@ +# Copilot Instructions for Steeltoe Documentation + +## Overview + +This repository hosts the [Steeltoe website](https://steeltoe.io/), which contains documentation and blog articles. The site is built with ASP.NET Core Blazor and is **heavily dependent on docfx**. + +## Technology Stack + +- **ASP.NET Core Blazor**: Web framework for the site +- **docfx**: Documentation generation tool (primary dependency) + - Generates API documentation from triple-slash comments in Steeltoe source code + - Converts Markdown documents to HTML + - Uses custom templates in `docs/modern-steeltoe` directory +- **PowerShell**: Build scripts +- **.NET**: Core runtime and tooling + +## Repository Structure + +- `/docs`: Content source files + - `/api`: Index pages for API Browser content + - `/articles`: Blog posts + - `/docs`: Steeltoe documentation (versioned: v2, v3, v4) + - `/guides`: Getting started guides + - `/modern-steeltoe`: Customized docfx template +- `/src`: Blazor website source code + - `/Steeltoe.io`: Main web application project +- `/build`: Build scripts and configuration + - `build-metadata.ps1`: Generates API Browser metadata + - `metadata.conf`: Configuration for Steeltoe source versions + - API configuration files: `api-v{version}.json`, `api-filter-v{version}.yml` + +## Building and Running + +### Quick Start (Local Development) + +```shell +dotnet run --project ./src/Steeltoe.io +``` + +Site runs at https://localhost:8080 + +> Note: First-time runs without processing static content will show warnings and 404 errors. + +### Full Build Process + +1. **Build API Browser metadata** (optional but recommended): + ```pwsh + pwsh ./build/build-metadata.ps1 + ``` + - Clones Steeltoe sources + - Generates API documentation for all versions + - Can target specific version: `./build-metadata.ps1 4` + - Can use local sources: `./build-metadata.ps1 source` + +2. **Process Markdown files only**: + ```shell + dotnet tool restore && dotnet docfx build docs/docfx.json --warningsAsErrors true + ``` + +### Clean Build + +```shell +git clean -xdff +``` + +## docfx Specifics + +### Configuration Files + +- `docs/docfx.json`: Local development config (excludes API Browser) +- `docs/docfx-all.json`: Full build config (includes API Browser) +- Output directory: `src/Steeltoe.io/wwwroot` + +### Markdown Guidelines + +- Use [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html) +- Internal links should use `.md` extensions, not `.html` +- Cross-references: Use `[link title](../example.md#section-title)` or UID-based xrefs +- Files can include YAML front matter for metadata and display options + +### YAML Front Matter Options + +- `_disableToc`: Hide left table of contents +- `_disableAffix`: Hide right page navigation +- `_disableContribution`: Hide "Edit this page" link +- `_enableSearch`: Show/hide search icon +- `_enableNewTab`: Open external links in new tab +- `_hideTocVersionToggle`: Hide version toggler +- `_noindex`: Prevent search engine indexing +- `_disableNavbar`: Hide top navigation bar + +### Creating Content + +#### New Blog Post + +1. Create `.md` file in `articles/` directory with URL-safe name +2. Add entry to `/articles/index.md` +3. Include required front matter: + ```yaml + --- + title: Post Title + description: Brief description + date: MM/DD/YYYY + uid: articles/url-safe-name + tags: [ "tag1", "tag2" ] + author.name: Author Name + author.github: username + author.twitter: handle + --- + ``` + +#### New Documentation Page + +1. Create `.md` file in appropriate version directory (e.g., `docs/v4/component/`) +2. Add to relevant `toc.yml` file +3. Use UID format: `docs/v{version}/component/page-name` + +## Testing and Validation + +- Run `dotnet docfx build docs/docfx.json --warningsAsErrors true` to validate Markdown +- Check for `InvalidFileLink` warnings +- Test site locally before committing +- Verify links and cross-references work correctly + +## Linting + +- Markdown linting configured in `.markdownlint.json` +- Editor configuration in `.editorconfig` + +## CI/CD + +- GitHub Actions workflows in `.github/workflows/` +- `build-and-stage.yml`: Main build and deployment +- Environment variable: `DOCFX_SOURCE_BRANCH_NAME` used during builds + +## Common Tasks + +### Update API Documentation + +```pwsh +cd build +pwsh ./build-metadata.ps1 +``` + +### Add New Steeltoe Version + +1. Update `build/metadata.conf` +2. Create `build/api-v{version}.json` +3. Create `build/api-filter-v{version}.yml` +4. Add version directories in `docs/` + +### Modify Templates + +Custom templates are in `docs/modern-steeltoe/` directory. Changes here affect site-wide styling and layout. + +## Best Practices + +1. **Always validate links**: Use `.md` extensions for internal links +2. **Test docfx builds**: Run build command to catch errors before committing +3. **Respect versioning**: Keep documentation organized by Steeltoe version +4. **Follow Markdown conventions**: Use docfx-flavored Markdown features +5. **Minimal changes**: This is a documentation site; changes should be surgical and precise +6. **Don't modify working code**: Unless fixing a bug related to your task +7. **Use existing tooling**: Leverage docfx commands for validation + +## Support and Resources + +- [docfx documentation](https://dotnet.github.io/docfx) +- [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html) +- [Steeltoe website](https://steeltoe.io) +- [ASP.NET Core Blazor docs](https://learn.microsoft.com/aspnet/core/blazor/) From f8f96864a19f69c03eb11cead75891365040c5da Mon Sep 17 00:00:00 2001 From: Tim Hess Date: Thu, 19 Feb 2026 14:47:59 -0600 Subject: [PATCH 3/4] use generic agent instructions, deduplicate some content --- .github/copilot-instructions.md | 171 -------------------------------- AGENTS.md | 44 ++++++++ 2 files changed, 44 insertions(+), 171 deletions(-) delete mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 6d22d77e..00000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,171 +0,0 @@ -# Copilot Instructions for Steeltoe Documentation - -## Overview - -This repository hosts the [Steeltoe website](https://steeltoe.io/), which contains documentation and blog articles. The site is built with ASP.NET Core Blazor and is **heavily dependent on docfx**. - -## Technology Stack - -- **ASP.NET Core Blazor**: Web framework for the site -- **docfx**: Documentation generation tool (primary dependency) - - Generates API documentation from triple-slash comments in Steeltoe source code - - Converts Markdown documents to HTML - - Uses custom templates in `docs/modern-steeltoe` directory -- **PowerShell**: Build scripts -- **.NET**: Core runtime and tooling - -## Repository Structure - -- `/docs`: Content source files - - `/api`: Index pages for API Browser content - - `/articles`: Blog posts - - `/docs`: Steeltoe documentation (versioned: v2, v3, v4) - - `/guides`: Getting started guides - - `/modern-steeltoe`: Customized docfx template -- `/src`: Blazor website source code - - `/Steeltoe.io`: Main web application project -- `/build`: Build scripts and configuration - - `build-metadata.ps1`: Generates API Browser metadata - - `metadata.conf`: Configuration for Steeltoe source versions - - API configuration files: `api-v{version}.json`, `api-filter-v{version}.yml` - -## Building and Running - -### Quick Start (Local Development) - -```shell -dotnet run --project ./src/Steeltoe.io -``` - -Site runs at https://localhost:8080 - -> Note: First-time runs without processing static content will show warnings and 404 errors. - -### Full Build Process - -1. **Build API Browser metadata** (optional but recommended): - ```pwsh - pwsh ./build/build-metadata.ps1 - ``` - - Clones Steeltoe sources - - Generates API documentation for all versions - - Can target specific version: `./build-metadata.ps1 4` - - Can use local sources: `./build-metadata.ps1 source` - -2. **Process Markdown files only**: - ```shell - dotnet tool restore && dotnet docfx build docs/docfx.json --warningsAsErrors true - ``` - -### Clean Build - -```shell -git clean -xdff -``` - -## docfx Specifics - -### Configuration Files - -- `docs/docfx.json`: Local development config (excludes API Browser) -- `docs/docfx-all.json`: Full build config (includes API Browser) -- Output directory: `src/Steeltoe.io/wwwroot` - -### Markdown Guidelines - -- Use [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html) -- Internal links should use `.md` extensions, not `.html` -- Cross-references: Use `[link title](../example.md#section-title)` or UID-based xrefs -- Files can include YAML front matter for metadata and display options - -### YAML Front Matter Options - -- `_disableToc`: Hide left table of contents -- `_disableAffix`: Hide right page navigation -- `_disableContribution`: Hide "Edit this page" link -- `_enableSearch`: Show/hide search icon -- `_enableNewTab`: Open external links in new tab -- `_hideTocVersionToggle`: Hide version toggler -- `_noindex`: Prevent search engine indexing -- `_disableNavbar`: Hide top navigation bar - -### Creating Content - -#### New Blog Post - -1. Create `.md` file in `articles/` directory with URL-safe name -2. Add entry to `/articles/index.md` -3. Include required front matter: - ```yaml - --- - title: Post Title - description: Brief description - date: MM/DD/YYYY - uid: articles/url-safe-name - tags: [ "tag1", "tag2" ] - author.name: Author Name - author.github: username - author.twitter: handle - --- - ``` - -#### New Documentation Page - -1. Create `.md` file in appropriate version directory (e.g., `docs/v4/component/`) -2. Add to relevant `toc.yml` file -3. Use UID format: `docs/v{version}/component/page-name` - -## Testing and Validation - -- Run `dotnet docfx build docs/docfx.json --warningsAsErrors true` to validate Markdown -- Check for `InvalidFileLink` warnings -- Test site locally before committing -- Verify links and cross-references work correctly - -## Linting - -- Markdown linting configured in `.markdownlint.json` -- Editor configuration in `.editorconfig` - -## CI/CD - -- GitHub Actions workflows in `.github/workflows/` -- `build-and-stage.yml`: Main build and deployment -- Environment variable: `DOCFX_SOURCE_BRANCH_NAME` used during builds - -## Common Tasks - -### Update API Documentation - -```pwsh -cd build -pwsh ./build-metadata.ps1 -``` - -### Add New Steeltoe Version - -1. Update `build/metadata.conf` -2. Create `build/api-v{version}.json` -3. Create `build/api-filter-v{version}.yml` -4. Add version directories in `docs/` - -### Modify Templates - -Custom templates are in `docs/modern-steeltoe/` directory. Changes here affect site-wide styling and layout. - -## Best Practices - -1. **Always validate links**: Use `.md` extensions for internal links -2. **Test docfx builds**: Run build command to catch errors before committing -3. **Respect versioning**: Keep documentation organized by Steeltoe version -4. **Follow Markdown conventions**: Use docfx-flavored Markdown features -5. **Minimal changes**: This is a documentation site; changes should be surgical and precise -6. **Don't modify working code**: Unless fixing a bug related to your task -7. **Use existing tooling**: Leverage docfx commands for validation - -## Support and Resources - -- [docfx documentation](https://dotnet.github.io/docfx) -- [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html) -- [Steeltoe website](https://steeltoe.io) -- [ASP.NET Core Blazor docs](https://learn.microsoft.com/aspnet/core/blazor/) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..7aad06ae --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# Agent instructions for Steeltoe Documentation + +## Scope and constraints + +- **This repo is primarily documentation.** Prefer minimal, surgical edits. Do not change application or build code unless the task explicitly requires it. +- **When editing docs only:** do not modify `.github/workflows/` or `src/`. +- **Version focus:** Steeltoe v4 is current; v2 and v3 are legacy. Prefer v4 paths and examples unless the task targets an older version. + +## Do / Don't + +| Do | Don't | +| --- | --- | +| Use `.md` extensions for internal links | Use `.html` in internal links | +| Run the docfx build (see [README.md](README.md)) before committing doc changes; fix `InvalidFileLink` and similar warnings | Commit doc changes without validating | +| Add new pages to the relevant `toc.yml` (see [docs/README.md](docs/README.md)) | Add new API version config without updating `build/metadata.conf` and the corresponding build API config files | +| Use [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html) | Change Blazor or workflow files unless the task explicitly requires it | + +## Where to find instructions + +**Use the READMEs as the source of truth.** Update them when build or content steps change; AGENTS.md only points to them. + +- **[README.md](README.md)** — Build order, commands to run the site locally, clean build (`git clean -xdff`). Run docfx before `dotnet run` or you get 404s and `InvalidFileLink` from `docs/api`. +- **[build/README.md](build/README.md)** — API Browser: script, version/source switches, what the script does. +- **[docs/README.md](docs/README.md)** — docfx layout, links and cross-references, YAML front matter options, creating blog posts and doc pages (including `toc.yml` examples). + +## Overview and layout + +This repository hosts the [Steeltoe website](https://steeltoe.io/): documentation and blog articles, built with ASP.NET Core Blazor and docfx. Key locations: + +- **`docs/`** — Content (see [docs/README.md](docs/README.md) for subdirs and content rules). +- **`src/Steeltoe.io/`** — Blazor app; docfx output goes to `wwwroot`. +- **`build/`** — API Browser script and config ([build/README.md](build/README.md)). +- **CI** — `.github/workflows/build-and-stage.yml`. + +## Linting and config + +- Markdown: `.markdownlint.json` +- Editor: `.editorconfig` + +## Resources + +- **Canonical instructions:** [README.md](README.md), [build/README.md](build/README.md), [docs/README.md](docs/README.md). +- [docfx documentation](https://dotnet.github.io/docfx) · [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html) +- [Steeltoe website](https://steeltoe.io) · [ASP.NET Core Blazor](https://learn.microsoft.com/aspnet/core/blazor/) From f94b2dbf2fff18a1df666f3dd54a70bde47f9ecd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Feb 2026 20:51:35 +0000 Subject: [PATCH 4/4] Update README metadata for docfx installation process Correct outdated references to .config/dotnet-tools.json to reflect the actual implementation where docfx binaries are downloaded directly by build-metadata.ps1 as a temporary workaround for .NET 10 support. Co-authored-by: TimHess <3947063+TimHess@users.noreply.github.com> --- build/README.md | 2 +- docs/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/build/README.md b/build/README.md index cc0de0fa..bcf86d17 100644 --- a/build/README.md +++ b/build/README.md @@ -22,7 +22,7 @@ This process can take a while to complete, will display many warnings and may in ## What does the script do? -1. Install docfx (by running `dotnet tool restore`, which installs tools defined in [dotnet-tools.json](../.config/dotnet-tools.json)) +1. Download docfx binaries (temporary workaround for .NET 10 support) 1. Clone several copies of Steeltoe (using [metadata.conf](./metadata.conf) to identify checkout targets) 1. Run `docfx metadata api-v{version}.json` for each copy 1. This command will produce many yaml files and place them in [docs](../docs), alongside the index pages for each API version diff --git a/docs/README.md b/docs/README.md index 8ddb9f52..73dc3608 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,7 @@ If you are working with API Browser content, view [this README](../build/README. ## Installing docfx -Install docfx by running `dotnet tool restore`, which installs tools defined in [dotnet-tools.json](../.config/dotnet-tools.json). +docfx is automatically downloaded by the [build-metadata.ps1](../build/build-metadata.ps1) script when building API Browser metadata. ## docfx Markdown