Skip to content

README.md

Latest commit

 

History

History
73 lines (61 loc) · 3.64 KB

README.md

File metadata and controls

73 lines (61 loc) · 3.64 KB
Raw

Askr website

Hydrated Askr marketing and documentation site, generated with Vite Plus and the Askr CLI, then deployed to GitHub Pages.

The website consumes published @askrjs/* packages from npm. Local builds and CI therefore validate the same package boundary used by GitHub Pages.

Commands

  • npm run dev starts the Vite development server.
  • npm run build builds the client, generates the AI-readable documentation, runs askr ssg into dist/, and validates the generated output.
  • npm run fmt:check checks formatting without changing files.
  • npm test runs the unit tests; generated-output contracts run automatically after npm run build.
  • npm run preview serves dist/ with vp preview --outDir dist.
  • npm run analyze runs Askr's framework-specific correctness analysis.
  • npm run check runs formatting, lint, typecheck, tests, and the production build.

Architecture

  • src/pages/marketing/_layout.tsx owns the marketing shell and shared Askr branding.
  • src/pages/_routes.tsx owns the complete browser and SSG route registry plus the persistent route-analytics layout, while src/pages/marketing/_routes.tsx registers the marketing leaves.
  • src/pages/marketing/home.tsx renders the / page.
  • src/pages/docs/catalog.ts is the typed source of truth for docs routes, metadata, grouped navigation, breadcrumbs, page ordering, search, and SSG.
  • src/pages/docs/ also owns the shared content primitives, responsive shell, generated API entrypoint pages, exhaustive Lucide gallery, and lazy search index.
  • src/pages/docs/markdown.ts renders that same catalog into clean per-page Markdown and the complete llms-full.txt corpus; public/llms.txt remains a concise, curated entry point.
  • src/main.tsx hydrates generated markup and starts the SPA in development.
  • public/assets/askr-logo-64.avif provides the in-page mark, with PNG favicon and touch-icon variants; the GitHub mark variants come from the official GitHub Brand Toolkit.
  • ssg.config.ts injects rendered HTML and route-specific metadata into Vite's built document and publishes its hashed assets.

The internal route registry is the only interface shared by the browser and SSG. This package does not expose a public API.

Build and publish flow

  1. npm run build:client builds the browser entry and stylesheet into .askr/client/ with hashed asset names.
  2. npm run build:llms generates one index.md alternate per documentation route plus llms-full.txt into the ignored .askr/ build tree.
  3. npm run build:ssg renders the marketing routes, authored docs catalog, and API reference routes, injects them into the built Vite document, and publishes the HTML, Markdown, and hashed assets to dist/.

The API and CLI snapshots are checked-in documentation data. The unit suite derives installed package entrypoints, versions, exported signatures, peer metadata, and CLI help directly from node_modules and fails on drift before the production build starts. Package versions remain internal contract metadata and are not rendered on the site. Reference-only packages are kept as development dependencies; packages used by live browser examples remain runtime dependencies.

.github/workflows/ci.yml runs format, lint/typecheck, build, and test on pull requests. Pushes to main and manual dispatches use .github/workflows/deploy.yml to run the aggregate check, upload dist/, and deploy it through the github-pages environment.

The repository does not carry a CNAME file. Configure askrjs.com in the repository's Pages settings (or through the Pages API), wait for DNS and the certificate to become healthy, then enable HTTPS enforcement.