Skip to content

Add comprehensive documentation site with Astro and Starlight - #3

Merged
eralmansouri merged 1 commit into
mainfrom
claude/stringent-docs-website-tg8u1c
Jul 6, 2026
Merged

eralmansouri merged 1 commit into
mainfrom
claude/stringent-docs-website-tg8u1c

Conversation

@eralmansouri

Copy link
Copy Markdown
Owner

Summary

This PR adds a complete documentation site for stringent built with Astro and Starlight, including guides, an interactive playground, and auto-generated API reference.

Key Changes

  • Documentation structure: Five comprehensive guides covering getting started, grammar definition, schemas & types, parsing & evaluation, and error handling
  • Interactive playground: A React component (ExpressionPlayground.tsx) that demonstrates the runtime engine with live parsing and evaluation against a sample schema
  • Architecture explanation: A detailed page explaining the dual-engine design and design rationale
  • Astro + Starlight setup: Full site configuration with TypeDoc integration for auto-generated API docs, Twoslash code block support for type-level examples, and GitHub Pages deployment
  • CI/CD: GitHub Actions workflow to build and deploy docs on changes to main
  • README update: Added link to the documentation site

Notable Implementation Details

  • The playground component uses the same grammar from the getting-started guide (numbers, strings, variables, paths, operators, ternary) and demonstrates both successful parsing/evaluation and error handling with positioned error messages
  • Code examples throughout the docs use Twoslash annotations to show inferred types at documentation build time, making the type-safety guarantees concrete and verifiable
  • The site is configured to deploy to https://eralmansouri.github.io/stringent/ via GitHub Pages
  • Documentation emphasizes the dual-engine design: compile-time validation for string literals via the type-level parser, and runtime safety for dynamic strings via structured errors

https://claude.ai/code/session_01RhdiHwoXKWe93LDY8eFopn

Scaffold a documentation website under docs/ built with Astro Starlight:

- Twoslash-powered code blocks (expressive-code-twoslash): examples
  compile against the real library at build time, with hover types
  showing the type-level engine's actual inference
- Guide pages ported from README.md (getting started, defining a
  grammar, schemas & types, parsing & evaluation, error handling) and
  an architecture page adapted from DESIGN.md
- API reference generated from src/index.ts via starlight-typedoc
- An interactive React playground island running safeParse/evaluateAst
  in the browser against the quickstart grammar
- GitHub Pages deploy workflow (builds the library, then the site)

The docs consume stringent via a link: dependency, so run the root
build before building docs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RhdiHwoXKWe93LDY8eFopn
@eralmansouri
eralmansouri merged commit 0826bf9 into main Jul 6, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants