Skip to content

Commit f62b1ba

Browse files
Rebuild the website with native motion and source API documentation
# TLDR; Rebuild the documentation website with an interactive HTTP outcome explorer, source-generated API references, and one shared prose style. Enforce a 2,500-byte total CSS budget and verify the site before GitHub Pages deployment. # Details - Replace the theme plugin with responsive local Eleventy layouts for English and Chinese homepages, guides, API pages, examples, and the journal. Preserve existing content and taxonomy routes while repairing broken links and duplicate headings. - Animate request/result paths directly in canvas. Outcome controls update the diagram and C# branches; keyboard navigation, reduced motion, pause/resume, offscreen suspension, and page restoration are supported. - Export public C# declarations and XML documentation through a Roslyn tool into Markdown and JSON reference pages, with overload anchors and source links. Compile and exercise the same example source rendered in both languages. - Reject CSS over 2,500 raw UTF-8 bytes, inline/external styles, CSS injection, missing routes, bad canonicals, and invalid crawl metadata during builds. Guides, articles, and API references share `.prose` typography. - Test root and GitHub Pages path-prefix builds. The Pages workflow runs export/guard tests and browser checks on PRs, then deploys verified main builds using the configured Pages origin and path. - Remove obsolete theme dependencies, update patched transitive packages, and make the preview command use its own port without terminating other services. # How Do The Tests Prove The Changes Work? Browser regressions exercise all three outcomes through repeated edits and compare actual canvas pixels for motion, pause, and reduced-motion behavior. They cover keyboard/mobile navigation, no-JavaScript content, translation routes, all generated API headings on mobile, and identical computed prose styles across documentation, blog, and API pages. Exporter fixtures change real declarations and XML comments, verify distinct/stable overload anchors and qualified symbol IDs, exclude private declarations, and require deterministic output. The shared examples compile against RestClient.Net 7.3.1 and pass 28 runtime assertions for requests, responses, errors, headers, factories, and cancellation without network requests. Build-guard fixtures prove the CSS limit rejects the 2,501st byte and cannot be bypassed by inline styles, external assets, SVG styles, or JavaScript injection. Final local validation: 105 browser tests passed with zero failures/skips; all 23 exporter, guard, and example tests pass; 110 generated pages pass the site audit at **2,491 / 2,500 CSS bytes**. Repository CSharpier and workflow actionlint checks pass.
1 parent 0b31a12 commit f62b1ba

76 files changed

Lines changed: 3692 additions & 4504 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/website-audit/SKILL.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@ description: Audits a website for SEO, AI search performance, structured data, m
66

77
## RestClient.Net context
88

9-
The website is in `Website/`, uses Eleventy and `eleventy-plugin-techdoc`, and builds with `npm ci` then `npm run build` from that directory. Edit sources, not `Website/_site/`. Use `npx @11ty/eleventy --serve --port=8081` for an isolated preview: the existing npm dev command terminates processes on port 8080. The deployment workflow is `.github/workflows/deploy-website.yml`.
9+
The website is in `Website/`, uses Eleventy with local layouts, and builds with `npm ci` then `npm run build` from that directory. It needs Node.js 22 and the .NET 9 SDK for source API export. Edit sources, not `Website/_site/` or generated `Website/src/api/reference/`. `npm run dev` previews on port 4173 without terminating other processes. The deployment workflow is `.github/workflows/deploy-website.yml`.
10+
11+
The user's total CSS budget is 2,500 raw UTF-8 bytes. Keep the local theme and shared `.prose` styling; do not reintroduce `eleventy-plugin-techdoc`, whose mandatory stylesheet alone exceeds that budget. `npm run build` audits the generated output. Run `npm run test:unit` and `npm test` for export, budget, accessibility, motion, and route regressions. Production URLs come from `SITE_URL` and `SITE_PATH_PREFIX`, populated by GitHub Pages metadata.
1012

1113
# Website Audit
1214

@@ -36,7 +38,7 @@ Audit Progress:
3638
- [ ] Step 12: Report findings
3739
```
3840

39-
- **Theme:** dev-tool/docs sites MUST use [`eleventy-plugin-techdoc`](https://github.com/Nimblesite/eleventy-plugin-techdoc) on Eleventy 3.x. Verify it is the theme in use, and **upgrade it (and `@11ty/eleventy`) to the latest version** before auditing, then rebuild and audit the upgraded output.
41+
- **Theme:** retain the repository's local Eleventy layouts and shared prose stylesheet within the user's CSS budget. Dependency upgrades are a separate authorized task; do not replace the theme as part of an audit.
4042
- Check the outputted HTML/CSS/JavaScript AFTER the website is generated by the static content generator. - Don't just check the static content before the website is generated.
4143
- Fix issues at the core where the static content templates are stored - not in the outputted HTML (e.g. _site)
4244
- Never manually edit the generated website content directly

‎.github/workflows/deploy-website.yml‎

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,86 @@
1-
name: Deploy Website to GitHub Pages
1+
name: Website
22

33
on:
4+
pull_request:
5+
branches:
6+
- main
47
push:
58
branches:
69
- main
710

811
permissions:
912
contents: read
10-
pages: write
11-
id-token: write
1213

1314
concurrency:
14-
group: "pages"
15+
group: "pages-${{ github.ref }}"
1516
cancel-in-progress: false
1617

1718
jobs:
1819
build:
1920
runs-on: ubuntu-latest
21+
timeout-minutes: 15
22+
permissions:
23+
contents: read
24+
pages: read
2025
steps:
2126
- name: Checkout code
2227
uses: actions/checkout@v4
2328

2429
- name: Setup Node.js
2530
uses: actions/setup-node@v4
2631
with:
27-
node-version: "20"
32+
node-version: "22"
2833
cache: "npm"
2934
cache-dependency-path: Website/package-lock.json
3035

36+
- name: Setup .NET for source API export
37+
uses: actions/setup-dotnet@v4
38+
with:
39+
dotnet-version: "9.0.x"
40+
3141
- name: Install dependencies
3242
working-directory: Website
3343
run: npm ci
3444

35-
- name: Build website
45+
- name: Test API export and website guards
46+
working-directory: Website
47+
run: npm run test:unit
48+
49+
- name: Build and audit local-root website
3650
working-directory: Website
3751
run: npm run build
3852

53+
- name: Install browser
54+
working-directory: Website
55+
run: npx playwright install --with-deps chromium
56+
57+
- name: Test website interactions and content
58+
working-directory: Website
59+
run: npm test
60+
3961
- name: Setup Pages
62+
id: pages
4063
uses: actions/configure-pages@v5
4164

65+
- name: Build and audit production URLs
66+
working-directory: Website
67+
env:
68+
SITE_URL: ${{ steps.pages.outputs.origin }}
69+
SITE_PATH_PREFIX: ${{ steps.pages.outputs.base_path }}
70+
run: npm run build
71+
4272
- name: Upload artifact
73+
if: github.event_name == 'push'
4374
uses: actions/upload-pages-artifact@v3
4475
with:
4576
path: Website/_site
4677

4778
deploy:
79+
if: github.event_name == 'push'
80+
permissions:
81+
contents: read
82+
pages: write
83+
id-token: write
4884
environment:
4985
name: github-pages
5086
url: ${{ steps.deployment.outputs.page_url }}

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ __pycache__/
2121
# Website
2222
Website/node_modules/
2323
Website/_site/
24+
Website/_site-prefix/
2425
Website/playwright-report/
2526
Website/test-results/
26-
Website/src/api/
27+
Website/src/api/reference/

‎AGENTS.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,12 @@ The existing dotnet commands are the local equivalents of the Makefile commands
2525

2626
Use .NET 8 and 9 runtimes for the repository's targets. Run focused tests while iterating, then the relevant CI checks. Preserve the existing assertions and regression coverage. Generated sample code is regenerated by the existing build targets.
2727

28+
## Website
29+
30+
The Eleventy site uses local layouts and a shared `.prose` class for docs, API references, and blog posts. Total shipped CSS must remain at or below **2,500 raw UTF-8 bytes**, including every stylesheet. Do not bypass the budget with inline styles, external CSS, or JavaScript that injects CSS. `npm run build` enforces the budget and checks generated links and metadata.
31+
32+
API reference pages are exported from C# declarations and XML comments by `Website/tools/ApiDocs/`; edit the source rather than generated `Website/src/api/reference/` files. Run `npm run test:unit`, `npm run build`, and `npm test` in `Website/`. The deployment workflow also verifies the GitHub Pages path prefix. See `Website/README.md`.
33+
2834
## Git and CI
2935

3036
Use a feature branch and a PR to `main`; derive the PR title and description from the diff with `origin/main`. Follow the user's authorization for committing, pushing, and merging. Monitor the latest PR commit's checks and resolve failures before merging. Do not add AI co-author trailers.

‎Website/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# RestClient.Net website
2+
3+
The site uses Eleventy, local layouts, and one shared `.prose` class for guides,
4+
API reference pages, and articles. Its interactive HTTP/Result diagram is drawn
5+
in canvas; the code examples and outcome controls remain ordinary accessible HTML.
6+
7+
## Develop and verify
8+
9+
Install Node.js 22 and the .NET 9 SDK, then run these commands from `Website/`:
10+
11+
```sh
12+
npm ci
13+
npm run dev
14+
```
15+
16+
The preview uses port 4173. It does not terminate other processes.
17+
18+
```sh
19+
npm run test:unit
20+
npm run build
21+
npm test
22+
```
23+
24+
The build exports API documentation, renders the site, and audits the result.
25+
The browser tests require Chromium: `npx playwright install chromium` installs it.
26+
27+
English and Chinese example pages render `examples/Program.cs`. The unit checks
28+
compile that source against RestClient.Net 7.3.1 and exercise requests and errors
29+
through a local message handler, without making network requests.
30+
31+
The CSS budget is **2,500 raw UTF-8 bytes across all shipped CSS files**. The build
32+
guard also rejects inline styles, external stylesheets, and JavaScript that injects
33+
CSS. Canvas drawing is used for the actual motion graphic, not to replace content
34+
layout or typography. Reduced-motion preferences and the animation pause control
35+
are respected.
36+
37+
## API reference
38+
39+
`npm run generate-api` runs `scripts/generate-api-docs.js`, which invokes the
40+
Roslyn exporter under `tools/ApiDocs/`. It reads public C# declarations and XML
41+
comments from the library source and writes deterministic Markdown and JSON to
42+
`src/api/reference/`. This generated directory is ignored by Git and recreated
43+
on every build. Edit C# declarations and comments to update the reference; curated
44+
API guides remain tracked under `src/api/`.
45+
46+
Exporter tests change fixture declarations and comments, exercise overloads, and
47+
check that private implementation details stay out of the reference.
48+
49+
## Deployment URLs
50+
51+
Local previews use root-relative routes. Set `SITE_URL` to the production origin
52+
and `SITE_PATH_PREFIX` to the mount path when deploying, for example:
53+
54+
```sh
55+
SITE_URL=https://melbournedeveloper.github.io \
56+
SITE_PATH_PREFIX=/RestClient.Net/ npm run build
57+
```
58+
59+
The GitHub Pages workflow reads these values from `actions/configure-pages`.
60+
It runs unit and browser tests before building and auditing the production URLs.
61+
Pull requests run these checks; only pushes to `main` deploy the resulting site.

‎Website/eleventy.config.js‎

Lines changed: 41 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,44 @@
1-
import techdoc from "eleventy-plugin-techdoc";
1+
import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";
2+
import markdownIt from "markdown-it";
3+
import anchor from "markdown-it-anchor";
24

3-
export default function(eleventyConfig) {
4-
eleventyConfig.addPlugin(techdoc, {
5-
site: {
6-
name: "RestClient.Net",
7-
url: "https://restclient.net",
8-
description: "The safest way to make REST calls in C#. Built with functional programming, type safety, and modern .NET patterns.",
9-
},
10-
features: {
11-
blog: true,
12-
docs: true,
13-
darkMode: true,
14-
i18n: true,
15-
},
16-
i18n: {
17-
defaultLanguage: 'en',
18-
languages: ['en', 'zh'],
19-
},
5+
const origin = process.env.SITE_URL || "https://melbournedeveloper.github.io";
6+
const prefix = "/" + (process.env.SITE_PATH_PREFIX || "").replace(/^\/+|\/+$/g, "") + "/";
7+
const basePath = prefix === "//" ? "/" : prefix;
8+
const absoluteUrl = value => new URL(String(value || "/").replace(/^\//,""), new URL(basePath,origin)).href;
9+
export default function (config) {
10+
config.addPlugin(syntaxHighlight);
11+
config.setLibrary("md", markdownIt({html:true,linkify:true}).use(anchor, {slugify:s=>s.toLowerCase().replace(/\s+/g,"-").replace(/[^\p{L}\p{N}_-]/gu,"")}));
12+
config.addPassthroughCopy("src/assets");
13+
config.addPassthroughCopy({"src/api/reference/api.json":"api/reference/api.json", "src/api/reference/schema.json":"api/reference/schema.json"});
14+
config.addCollection("posts", api=>api.getFilteredByGlob("src/blog/*.md").sort((a,b)=>b.date-a.date));
15+
config.addCollection("zhposts", api=>api.getFilteredByGlob("src/zh/blog/*.md").sort((a,b)=>b.date-a.date));
16+
config.addCollection("journalArchives", api => {
17+
const archives = [];
18+
for (const lang of ["en", "zh"]) {
19+
const prefix = lang === "zh" ? "/zh" : "";
20+
const posts = api.getFilteredByGlob(`src${prefix}/blog/*.md`).sort((a,b)=>b.date-a.date);
21+
for (const kind of ["tags", "categories"]) {
22+
archives.push({url:`${prefix}/blog/${kind}/`,lang,title:lang === "zh" ? (kind === "tags" ? "博客主题" : "博客分类") : (kind === "tags" ? "Journal topics" : "Journal categories"),posts});
23+
const values = [...new Set(posts.flatMap(p=>kind === "tags" ? (p.data.tags || []).filter(t=>!["post","posts"].includes(t)) : p.data.category ? [p.data.category] : []))];
24+
for (const value of values) archives.push({url:`${prefix}/blog/${kind}/${value.toLowerCase().replace(/[^a-z0-9]+/g,"-")}/`,lang,title:(lang === "zh" ? "博客 / " : "Journal / ")+value,posts:posts.filter(p=>kind === "tags" ? (p.data.tags || []).includes(value) : p.data.category === value)});
25+
}
26+
}
27+
return archives;
2028
});
21-
22-
eleventyConfig.addPassthroughCopy("src/assets");
23-
24-
return {
25-
dir: { input: "src", output: "_site" },
26-
markdownTemplateEngine: "njk",
27-
pathPrefix: "/RestClient.Net/",
28-
};
29+
config.addCollection("publicPages", api=>api.getAll().filter(p=>p.url && !p.data.eleventyExcludeFromCollections));
30+
config.addFilter("isoDate", value=>new Date(value).toISOString());
31+
config.addFilter("dateFormat", value=>new Date(value).toLocaleDateString("en",{year:"numeric",month:"long",day:"numeric",timeZone:"UTC"}));
32+
config.addFilter("xmlEscape", value=>String(value??"").replace(/[<>&"']/g,c=>({"<":"&lt;",">":"&gt;","&":"&amp;",'"':"&quot;","'":"&apos;"}[c])));
33+
config.addFilter("absoluteUrl", absoluteUrl);
34+
config.addFilter("translationUrl", (url,lang,pages=[])=>{const route=(lang==="zh"?"/zh":"")+url.replace(/^\/zh(?=\/)/,"");return pages.some(p=>p.url===route)?route:(lang==="zh"?"/zh/":"/");});
35+
config.addFilter("hasTranslation",(url,lang,pages=[])=>pages.some(p=>p.url===(lang==="zh"?"/zh":"")+url.replace(/^\/zh(?=\/)/,"")));
36+
config.addFilter("section", url=>url.replace(/^\/zh(?=\/)/,"").split("/")[1]||"home");
37+
config.addFilter("withoutHeading", html=>html.replace(/<h1[^>]*>[\s\S]*?<\/h1>/,""));
38+
config.addFilter("json", value=>JSON.stringify(value).replace(/</g,"\\u003c"));
39+
config.addTransform("deploymentPaths", function (content) {
40+
if (!(this.page?.outputPath || this.outputPath || "").endsWith(".html") || basePath === "/") return content;
41+
return content.replace(/(href|src|action)=("|')\/(?!\/)([^"']*)\2/g, (all,attr,quote,path)=>`${attr}=${quote}${path.startsWith(basePath.slice(1))?"/":""}${path.startsWith(basePath.slice(1))?path:basePath+path}${quote}`);
42+
});
43+
return {dir:{input:"src",output:"_site"},markdownTemplateEngine:"njk",pathPrefix:basePath};
2944
}
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<Project>
2+
<PropertyGroup>
3+
<TargetFramework>net9.0</TargetFramework>
4+
<ImplicitUsings>enable</ImplicitUsings>
5+
<Nullable>enable</Nullable>
6+
<EnableNETAnalyzers>false</EnableNETAnalyzers>
7+
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
8+
</PropertyGroup>
9+
<ItemGroup>
10+
<PackageReference Include="RestClient.Net" Version="7.3.1" />
11+
</ItemGroup>
12+
</Project>

‎Website/examples/Examples.csproj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup>
3+
<OutputType>Exe</OutputType>
4+
</PropertyGroup>
5+
<ItemGroup>
6+
<Compile Remove="Tests/**/*.cs" />
7+
</ItemGroup>
8+
</Project>

‎Website/examples/Program.cs‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
using System.Net.Http.Json;
2+
using Outcome;
3+
using RestClient.Net;
4+
using Urls;
5+
6+
namespace WebsiteExamples;
7+
8+
public static class RestClientExamples
9+
{
10+
// This runnable entry point calls JSONPlaceholder. Tests use a local handler instead.
11+
public static async Task Main()
12+
{
13+
using var client = new HttpClient();
14+
using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(15));
15+
var result = await GetPostAsync(client, 1, cancellation.Token);
16+
Console.WriteLine(Describe(result));
17+
}
18+
19+
public static Task<Result<Post, HttpError<string>>> GetPostAsync(
20+
HttpClient client,
21+
int id,
22+
CancellationToken cancellationToken = default
23+
) =>
24+
client.GetAsync(
25+
url: $"https://jsonplaceholder.typicode.com/posts/{id}".ToAbsoluteUrl(),
26+
deserializeSuccess: ReadPostAsync,
27+
deserializeError: ReadErrorAsync,
28+
headers: new Dictionary<string, string> { ["Accept"] = "application/json" },
29+
cancellationToken: cancellationToken
30+
);
31+
32+
public static Task<Result<Post, HttpError<string>>> CreatePostAsync(
33+
HttpClient client,
34+
CreatePost request,
35+
CancellationToken cancellationToken = default
36+
) =>
37+
client.PostAsync(
38+
url: "https://jsonplaceholder.typicode.com/posts".ToAbsoluteUrl(),
39+
requestBody: JsonContent.Create(request),
40+
deserializeSuccess: ReadPostAsync,
41+
deserializeError: ReadErrorAsync,
42+
cancellationToken: cancellationToken
43+
);
44+
45+
// Register a named client with services.AddHttpClient("posts") in your application.
46+
public static Task<Result<Post, HttpError<string>>> GetUsingFactoryAsync(
47+
IHttpClientFactory factory,
48+
int id,
49+
CancellationToken cancellationToken = default
50+
) =>
51+
factory.GetAsync(
52+
clientName: "posts",
53+
url: $"https://jsonplaceholder.typicode.com/posts/{id}".ToAbsoluteUrl(),
54+
deserializeSuccess: ReadPostAsync,
55+
deserializeError: ReadErrorAsync,
56+
cancellationToken: cancellationToken
57+
);
58+
59+
// Both success and failure are explicit. HTTP failures retain the response body.
60+
public static string Describe(Result<Post, HttpError<string>> result) =>
61+
result.Match(
62+
onSuccess: post => $"Post {post.Id}: {post.Title}",
63+
onError: error =>
64+
error.Match(
65+
onException: exception => $"Connection failed: {exception.Message}",
66+
onErrorResponse: (body, status, headers) => $"HTTP {(int)status}: {body}"
67+
)
68+
);
69+
70+
// Deserialize<T> receives HttpResponseMessage: read its Content property.
71+
private static async Task<Post> ReadPostAsync(
72+
HttpResponseMessage response,
73+
CancellationToken cancellationToken
74+
) =>
75+
await response.Content.ReadFromJsonAsync<Post>(cancellationToken)
76+
?? throw new InvalidDataException("The response contained no post.");
77+
78+
private static Task<string> ReadErrorAsync(
79+
HttpResponseMessage response,
80+
CancellationToken cancellationToken
81+
) => response.Content.ReadAsStringAsync(cancellationToken);
82+
}
83+
84+
public sealed record Post(int UserId, int Id, string Title, string Body);
85+
86+
public sealed record CreatePost(int UserId, string Title, string Body);
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup>
3+
<OutputType>Exe</OutputType>
4+
<StartupObject>WebsiteExamples.ExampleTests</StartupObject>
5+
</PropertyGroup>
6+
<ItemGroup>
7+
<Compile Include="../Program.cs" Link="DocumentedExample.cs" />
8+
</ItemGroup>
9+
</Project>

0 commit comments

Comments
 (0)