Meet the new Hardkoded docs
Meet the new Hardkoded docs.
Lately I added three projects to my open source portfolio. TypeSafe SDK .NET (a.k.a. JEV for .NET), E2E .NET, and Vercel AI for .NET. I’m also working on a native Playwright version. That one is still in progress.
I mentioned this before. Nowadays, getting the work done is easy. Marketing is my weak spot. Today, you need a good website and clear tutorials so the developer/agent can ramp up quickly.
DocFX falls short for that. I do this for love of the community in my free time, so I need something better.
I wrote a DocFX tutorial back in 2018. XML comments in, GitHub Pages out. It worked. Search, dark mode, the sidebar, the look: dated next to the Mintlify-style docs I actually like opening. I wanted that UX, and I wanted to stay on GitHub Pages.
So the site moved to Starlight. DocFX stayed in the pipeline, one step earlier.
Here they are:
Why the old site felt dated
DocFX is still good at one job. It reads a .NET project and emits an API model. The website it builds on top of that model is the part that felt old. Search, dark mode, the sidebar, the whole look and feel.
I don’t have a bug list to wave around. The pages worked. I wanted a site I was happy to send people to.
Why Starlight
Starlight is the Astro docs theme. Open source. The build is a static site, so GitHub Pages can host it the same way it hosted DocFX. Search ships with the production build. Dark mode ships with the theme. It looks like the docs sites I was jealous of.
The goal was a Mintlify-like UX without leaving GitHub Pages. That was the whole brief.
DocFX still reads the code
Starlight has no idea what a C# uid is. DocFX does. The API reference still starts there. DocFX stops at the YAML, and Starlight is the website.
npm run api restores the local DocFX tool and runs docfx metadata. That writes YAML. A small script turns the YAML into Markdown under docs-site/src/content/docs/api/, and Starlight renders that. Member headings keep the old DocFX anchors (#E2E_App_OpenAsync_... and the same idea on the other repos).
The generated Markdown is committed. npm run dev can start without the .NET SDK. CI runs npm run api again before npm run build, so the published site matches the code on that commit.
Three sites, same move
The first one was e2e-dotnet, in pull request 667. It is live: hardkoded.github.io/e2e-dotnet.
The site lives in docs-site/ on @astrojs/starlight. The accent is the logo blue, #4fa8ff. Links in light mode are #0c74d4. npm run sync copies README.md, COMPATIBILITY.md, and CONTRIBUTING.md into the site. The rest of the guides live in docs-site/. The API reference comes from E2E, E2E.NUnit, and E2E.XUnit.V3.
Same pattern on typesafe-sdk-dotnet, pull request 28. Live: hardkoded.github.io/typesafe-sdk-dotnet. Gold stayed gold, #e3a008 on the dark theme and #b87d06 in light mode. Guides sit in docs-site/guides/. The API comes from src/TypeSafe.AI.Sdk.
And the Vercel AI SDK for .NET, pull request 787. Live: hardkoded.github.io/vercel-ai-sdk-dotnet. Accent is violet, #7c5cff in the dark theme and #5b3fd4 in light mode. Guides come from docs/articles/. The API comes from src/Vercel.AI. It is a community port, not an official Vercel product.
Still GitHub Pages
All three repos use .github/workflows/docs.yml. A pull request builds the site. A push to main builds it and deploys with actions/deploy-pages. That is the only deploy.
On e2e-dotnet, docs used to publish when a version tag went out. That path is gone. Docs publish from main. A release tag does not ship the site anymore.
Old DocFX .html URLs redirect to the new paths. The redirect page keeps location.hash when JavaScript runs, so a member link still lands on the member. A browser that only follows the meta refresh drops the hash. Worth knowing.
One aside, because it bit the runner. Astro wants Node >=22.23.4. The "22" alias on GitHub Actions resolved to 22.23.3. Close enough to fail. The workflow pins >=22.23.4 <23 and sets check-latest: true.
Final words
DocFX still reads the assemblies. Starlight is the site. Pages still hosts it, from main.
Meet the new Hardkoded docs: E2E for .NET, TypeSafe.AI.Sdk, and the Vercel AI SDK for .NET.
I know they are not super pretty yet. Step by step.
Don’t stop coding!