docs: finish and deploy the Astro documentation site - #650
Open
unional wants to merge 5 commits into
Open
Conversation
The site under `apps/website` was the unmodified Starlight starter with a few real pages grafted on, and it was never deployed. This finishes it. Site config: - Set `site` + `base` so URLs resolve under https://cyberuni.github.io/type-plus/. Without `base` every internal link 404s once deployed. - Add `editLink` pointing at `apps/website/` on main. - Fix the `logo` paths: they pointed at `/public/type-plus.svg`, which Astro cannot resolve. Moved the asset to `src/assets/` and referenced it there. - Add `src/env.d.ts` for the generated content types. Documentation: - 13 new API pages covering object, array, tuple, string, number/numeric, boolean/logical, union/mix_types, function/functional, promise, nominal, type guards & assertions, math/bigint, and testing. Written from the .ts sources rather than the v7-era `src/*/readme.md` files, which are stale. - Rewrite index.mdx: the starter "Next steps" cards are replaced with real entry points, and the dead `/api/toc` hero link is removed. - Expand getting-started with install tabs and a branching-options primer. - Repoint every `unional/type-plus` GitHub link to `cyberuni/type-plus`. - Delete the starter leftovers: README.md, guides/example.md, houston.webp. Build: - turbo.json referenced a `pages#build` task, but the package is named `website`, so the entry never matched anything. Renamed and given real inputs/outputs; `.astro/**` added to the build outputs. - Add deploy-docs.yml, mirroring cyber-asana's. It also runs `pnpm build:doc` and nests the typedoc output at `/typedoc/` so the generated reference survives the move off the gh-pages branch. Verified: `astro build` produces 22 pages, and every internal link resolves with the base prefix applied. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ETjy9oQGyETyFmDBdR9Egz
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #650 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 43 43
Lines 232 232
Branches 51 51
=========================================
Hits 232 232 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
The Astro site now carries hand-written API documentation, so the generated typedoc dump no longer earns its place — and it cannot coexist with the new Pages deployment anyway, since a repo has exactly one Pages source and the Astro site is taking it. Removed: - the `docgen` job in release.yml, which pushed typedoc output to gh-pages - `.config/typedoc.jsonc` - the `build:doc` script, its `verify:pkg` step, and its turbo task - `typedocOptions` from packages/type-plus/tsconfig.json - the typedoc devDependency (lockfile updated; CI runs --frozen-lockfile) - the typedoc build/copy steps from deploy-docs.yml `/docs` stays in .gitignore. Nothing generates it any more, but existing checkouts still hold ~9MB of old output and it should not become committable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ETjy9oQGyETyFmDBdR9Egz
Adds `expressive-code-twoslash` to the Starlight site. Code blocks tagged
```ts twoslash are run through the real TypeScript compiler at build time, so
hovers show the types type-plus actually produces and `^?` queries print the
resolved result. For a type-level library that is the difference between
documenting behaviour and asserting it.
Two supporting changes make that possible:
- The site now depends on `type-plus` (workspace:*). twoslash resolves imports
for real, so the docs must see the built .d.ts. This also makes turbo's
`^build` actually build the library before the site, which it previously did
not because no dependency existed.
- Adds `typescript` (catalog:), a twoslash peer.
It immediately earned its place. The branching-options example claimed
IsString<any> // boolean — `any` is both
The compiler disagrees: `IsString<any>` is `false`. `boolean` comes from union
distribution (`IsString<string | 1>`), not from `any`. The example now shows
both cases and every line is checked at build time.
Note `expressive-code-twoslash@0.6.1` declares a peer of expressive-code
`^0.41.7` while Starlight 0.41.10 brings 0.44.1. That range is stale metadata,
not a real incompatibility — verified by asserting the rendered output contains
the resolved types rather than trusting a green build.
The 13 API pages are not converted yet; they can move over incrementally.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ETjy9oQGyETyFmDBdR9Egz
`pnpm add typescript@catalog:` rewrote the shared catalog from `~5.6.0` to `~5.6.3`, pinning it to whatever happened to be resolved at the time. That is a repo-wide change to every package's TypeScript range and had nothing to do with adding twoslash, so put it back. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ETjy9oQGyETyFmDBdR9Egz
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The site under `apps/website` was the unmodified Starlight starter with a few real pages grafted on, and it has never been deployed. This finishes it, replaces typedoc with it, and wires up deployment.
Site config
Documentation
typedoc is retired
A repo has exactly one Pages source, and the Astro site is taking it. The hand-written pages supersede the generated dump, so typedoc is removed rather than nested somewhere:
`/docs` stays in `.gitignore`: nothing generates it any more, but existing checkouts still hold ~9MB of old output that should not become committable.
Build
Pages is on `build_type: legacy`, source `gh-pages`. `actions/deploy-pages` will fail until the Pages source is switched to GitHub Actions in repo settings. The old typedoc URLs under `/type-plus/*` go away when that happens — that is the intended outcome.
Verification
`astro build` produces 22 pages; a link check across the built output found 0 broken internal links and 0 links missing the base prefix.
Not addressed
Two likely source bugs surfaced while reading the sources, documented as-tested rather than as-specified:
🤖 Generated with Claude Code
https://claude.ai/code/session_01ETjy9oQGyETyFmDBdR9Egz