feat: add elm-pages documentation site by ryanbas21 · Pull Request #27 · ryanbas21/devtools

ryanbas21 · 2026-05-12T06:12:19Z

Summary

Add a static documentation site built with elm-pages v3 at packages/docs-site/
17 pages across 5 sections: landing page, guides (7), package overviews (4), architecture diagram, contributing docs (4)
Hybrid content: Markdown for prose pages, hand-written Elm for interactive architecture diagram and landing page
Client-side search, dark/light mode toggle, Prism.js syntax highlighting, responsive sidebar layout
GitHub Pages deployment workflow triggered on pushes to main
All content verified against actual source code — real function names, type signatures, and CLI options

Pages

Section	Pages
Landing	1
Guides	7 (getting-started, devtools-extension, vscode-extension, tree-shaking, davinci-integration, journey-integration, oidc-integration)
Packages	4 (treeshake-check, eslint-plugin-treeshake, devtools-bridge, devtools-types)
Architecture	1 (interactive SVG diagram)
Contributing	4 (development-setup, repository-structure, code-style, release-process)

Tech Stack

elm-pages 3.5.1 + Lamdera compiler
dillonkearns/elm-markdown with custom callout renderer
Prism.js for syntax highlighting (TypeScript, Bash, JSON, YAML, Elm, JavaScript)
Plain CSS with CSS custom properties (dark/light mode)
GitHub Actions for deployment

Test Plan

pnpm build passes in packages/docs-site/
All 17 routes generate as static HTML
Markdown pages render with callout support
Architecture page shows SVG package diagram
Content audit — all function names, CLI args, type signatures verified against source
Visual verification in browser (dev server)
Search filters results correctly
Dark/light mode toggle works across full viewport
Responsive layout on mobile viewport

🤖 Generated with Claude Code

Initialize elm-pages v3.5.1 scaffold under packages/docs-site with monorepo-appropriate package.json. Adds lamdera, elm-review, and elm-codegen as required devDependencies. Adds lamdera to root pnpm onlyBuiltDependencies to allow its postinstall binary download. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Modify the elm-pages scaffold to include a sticky header with nav links, a collapsible sidebar with navigation sections, and a styled main content area. Replace default CSS with full docs site stylesheet supporting light/dark mode, responsive breakpoints, and typography. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add hand-written Elm modules for API documentation: - ApiDocs.Types: data types for API docs (ApiModule, TypeDoc, FunctionDoc) - ApiDocs.TreeshakeCheck: treeshake-check package documentation - Route.Api.Package_.ModuleName_: pre-rendered API reference pages - API reference and architecture CSS styles - Fix pre-existing ephemeral field disagreement in Blog, Docs, Contributing, and Packages routes by referencing description fields in view functions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add static Architecture route showing how wolfcola devtools packages relate to each other. Includes: - SVG diagram with package boxes grouped by tool family (OIDC DevTools and Tree-Shake Tools) with dependency arrows - Package relationships description list - Helper functions for SVG primitives (svgBox, svgGroup, svgArrow) - elm/svg dependency added to elm.json Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ributing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…tection Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…DC integration guides Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Dark mode now applies background/color on the [data-theme] wrapper which spans min-height: 100vh, so the entire page goes dark - Header nav links now point to actual existing pages instead of nonexistent index routes (/packages -> /packages/treeshake-check, etc.) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…atch real code - Delete all ApiDocs Elm modules (Types, TreeshakeCheck, EslintPluginTreeshake, DevtoolsBridge, DevtoolsTypes) and the API route (Route.Api.Package_.ModuleName_) - Remove API link from header nav in Shared.elm - Remove .api-reference, .api-item, .api-signature, .api-example CSS rules - Rewrite devtools-bridge package page with real exports: attachDaVinciBridge, attachJourneyBridge, attachOidcBridge, emitAuthEvent, emitConfigEvent, DEVTOOLS_EVENT_NAME, BridgeHandle, DevtoolsOptions - Rewrite devtools-types package page with real schemas: AuthEventSchema, NetworkDataSchema, SdkDataSchema, SdkConfigDataSchema, DomDataSchema, SessionDataSchema, JourneyDataSchema, OidcDataSchema, FlowStateSchema, FlowSummarySchema, FlowExportSchema, OIDC semantic schemas - Rewrite treeshake-check package page with real CLI options and programmatic API: checkPackage, analyzeTreeshakeability, getEntryFromPackageJson, error classes - Rewrite eslint-plugin-treeshake package page with real single rule (no-treeshake-hazard) and its check categories, configs (recommended/strict) - Rewrite DaVinci integration guide: attachDaVinciBridge with Subscribable interface - Rewrite Journey integration guide: attachJourneyBridge with RTK Query state - Rewrite OIDC integration guide: attachOidcBridge with endpoint-to-phase mapping - Fix stale ApiDocs references in contributing docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix treeshake-check CLI syntax (no positional args, use --cwd) - Fix event type examples in devtools-extension.md (use real schema types) - Fix unpacked extension path (manifest.json is in package root) - Fix vscode extension ID and name (oidc-devtools by ryanbasmajian) - Fix createBridge reference to attachDaVinciBridge in vscode docs - Fix test file location (co-located in src/, not in test/) - Fix eslint-plugin docs (add missing Object.defineProperties) - Fix repository-structure.md (correct vscode path, add devtools-core/ui) - Fix tree-shaking.md (remove barrel file claim, accurate tool description) - Remove scaffold leftover routes (Greet, Hello, Blog) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The bridge requires Ping Identity SDK Subscribable interfaces, not arbitrary OIDC clients. Updated callout to list the actual supported SDKs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The elm-pages docs-site contains Elm files and generated JS that the TypeScript ESLint parser cannot handle, causing ESLint to hang indefinitely in CI. Exclude the entire package since it uses Elm (not TypeScript) and has its own tooling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The docs site is a deployable Elm app, not a publishable TypeScript library. Moving it to apps/ separates it from the package pipeline (lint, test, typecheck) and avoids ESLint/TypeScript tooling conflicts. - Move packages/docs-site → apps/docs - Add apps/* to pnpm-workspace.yaml - Update ESLint ignores, CI workflow paths, and content references Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ryanbas21 and others added 23 commits May 11, 2026 23:11

chore: add .worktrees/ to gitignore

d2f3ff1

feat(docs-site): add landing page with package cards

b1d003b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add Markdown renderer with callout support

a202855

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add docs route for Markdown guide pages

3abbc79

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add packages route for package overview pages

df162b9

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add contributing route for contributor docs

c99bd5c

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add client-side search over content index

cd46c49

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add all content pages for guides, packages, and cont…

00e1794

…ributing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add API reference docs for all published packages

6ccfcbc

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add dark/light mode toggle with system preference de…

d3227c6

…tection Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(docs-site): add Prism.js syntax highlighting for code blocks

a81157b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ci: add GitHub Pages deployment workflow for docs site

2fd1041

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(docs-site): rename ForgeRock to Ping Identity, add Journey and OI…

be778d4

…DC integration guides Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(docs-site): correct bridge description — not framework-agnostic

811d3bf

The bridge requires Ping Identity SDK Subscribable interfaces, not arbitrary OIDC clients. Updated callout to list the actual supported SDKs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ryanbas21 merged commit e041455 into main May 12, 2026
1 check passed

ryanbas21 deleted the feat/docs-site branch May 12, 2026 15:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add elm-pages documentation site#27

feat: add elm-pages documentation site#27
ryanbas21 merged 23 commits into
mainfrom
feat/docs-site

ryanbas21 commented May 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ryanbas21 commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Pages

Tech Stack

Test Plan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ryanbas21 commented May 12, 2026 •

edited

Loading