Site Authoring Capabilities

This is the single source of truth for what ZajLibrary gives you to build pages with. Constitution (AGENTS.md), the starlight-content-author skill, and the Cursor rules all point here — so this page is what they describe.

Before you build

Reach for an existing plugin / component / token before adding anything custom. If you genuinely need something new, follow AGENTS.md (stack is pinned; build must stay green).

Wired plugins (live in app/astro.config.mjs)

These are active right now. Use them — don’t reinvent them.

Plugin	Use it for
Local zaj-mermaid integration + mermaid	```mermaid fenced diagrams (flow / sequence / graph). Markdown conversion uses Astro 6’s markdown.processor API.
starlight-theme-rapide	Base theme (its CSS is the base layer; tokens.css + theme.css still win).
starlight-sidebar-topics	Top navigation topics (Learn · Build · Resources · Collections · Directories · System docs), with shelves autogenerated and Collections generated from metadata.
starlight-auto-sidebar	Tune an autogenerated group (order / label / badge) via a per-folder _meta.yaml.
starlight-heading-badges	Status badges on headings — drive with status: current|target|future|draft.
starlight-auto-drafts	draft: true pages are hidden in the prod build, visible in dev.
starlight-links-validator	Build-time gate — fails npm run build on any broken internal link.
starlight-scroll-to-top	Scroll-to-top button.
starlight-image-zoom	Click-to-zoom images (legible screenshots).
starlight-github-alerts	GitHub-style alerts: > [!NOTE], > [!WARNING], > [!TIP], …
starlight-llms-txt	Generates llms.txt (machine-readable site summary).
@lorenzo_lewis/starlight-utils	Nav utilities — breadcrumbs (navLinks) and multi-sidebar switcher (multiSidebar). Wired with empty config today (compatible with sidebar-topics); enable options when IA needs them.
starlight-kbd	Platform-aware <Kbd> shortcuts + header keyboard-type picker (macOS / Windows).
starlight-markdown-blocks	Custom ::: blocks — idea, decision, start, next, summary.
starlight-tags	Tag index pages from tags: frontmatter.

Installed but parked

Package	Why it is parked
starlight-videos	Not wired today because it owns the same Starlight PageTitle and MarkdownContent override slots as the Zaj copy controls and image/code helpers. Re-enable only when a real video-guide page needs it, then rebuild the override chain deliberately.

Code blocks (Expressive Code — expressiveCode in astro.config.mjs)

Feature	Behavior
Word wrap (default)	All fenced code ships with wrap: true. Bash/sh/zsh use preserveIndent: false (terminal-style). Override per fence with wrap=false in the opening fence meta.
Copy button	Built into every frame (Expressive Code frames plugin).
Wrap / scroll toggle	Per block — button on each frame (left of copy) toggles only that block. Reload / navigation restores the build default (wrapped). Script: src/scripts/code-wrap-toggle.ts; styles in theme.css §8.

MDX component packages (no plugins: [] entry)

Import in .mdx only — no Starlight plugin registration required.

Package	Use it for
starlight-package-managers	npm/pnpm/yarn/bun tabs on install commands (<PackageManagers>)
starlight-showcases	Showcase cards — text, images, quotes, profiles, YouTube/Twitter embeds

Installed but blocked (Astro 6 / Zod 4)

Package	Issue
starlight-changelogs	v0.5.0 calls z.url() — not available in Zod 4 (z.string().url()). Static fallback: /zajlibrary/system/platform/resources/reference/changelog/. Full inventory: /zajlibrary/system/platform/resources/reference/starlight-plugins-used/.

Custom components (app/src/components/)

Import into a .mdx file (components don’t run in .md). Use the ~ alias instead of deep relative paths — import X from '~/components/diagrams/X.astro' (~ → app/src).

Component	Use it for
Stepper.astro	Numbered step-flow; saves per-step progress to localStorage; re-inits on astro:page-load.
DirectoryGrid.astro	Filterable card grid over a data collection (vanilla JS search + type filter).
Head.astro	Starlight Head override that enables site-wide View Transitions. Global — don’t import per-page.
PageTitle.astro	Starlight PageTitle override — adds the Copy as prompt button (header).
Footer.astro	Starlight Footer override — repeats Copy as prompt after article body (before pagination).
PageCopyPrompt.astro	Builds clipboard payload from page-prompt.ts; shared by title bar + footer.
CopyPageButton.astro	Clipboard + ChatGPT/Claude deep links; placement prop flips caret menu for footer.
diagrams/DiagramFigure.astro	Reusable frame for any diagram: title + responsive canvas + caption. Wrap your <svg> (or a ported diagram) in it.
diagrams/RuntimeOwnership.astro	Ready-made “central runtime authority + workers” diagram (incl. the bypass anti-pattern). Props: title, caption.
diagrams/StageFlow.astro	Left-to-right pipeline of stages (phase plans, deploy/content flows) — pass stages as props; responsive + ambient motion.
diagrams/PackageBoundary.astro	Ready-made “what talks to what” boundary/ownership map (good/split node tints). Props: title, caption.
diagrams/LayerStack.astro	Stacked architecture tiers (UI → runtime → data) with optional sub-component chips. Pass layers as props; tone: 'core' emphasizes a layer.
diagrams/StepStack.astro	Vertical numbered procedure where each step needs a sentence (semantic <ol>, mobile-friendly). Pass steps. Distinct from StageFlow (horizontal, label-only).
diagrams/Timeline.astro	Phases over time with status (done/current/future → colour + shape + label). Pass phases; pairs with the status content model.
diagrams/PatternPair.astro	Side-by-side before/after (anti-pattern ↔ pattern) via before/after slots — the highest-leverage teaching visual.
diagrams/DecisionTree.astro	Props-driven branching decision map — pass a DecisionTreeGraph; replaces Mermaid for labeled branches + outcome links.
diagrams/DecisionTreeWizard.astro	Interactive walk-through on the same graph — breadcrumb, choices, recommendation CTA, optional persistKey.
diagrams/ContentDecisionTree.astro	Preset content-IA tree (thin wrapper over DecisionTree).

See them live in Reusable Doc Components — which also carries the when-to-use-which decision table.

The .zaj-diagram-* class system (app/src/styles/diagrams.css)

Global, token-mapped SVG primitives so hand-authored inline SVG in any .mdx matches the components — and stays themed in light + dark with zero hardcoded hex:

• .zaj-diagram — the <svg> canvas (responsive; pair with a viewBox).
• .zaj-diagram-path (+ .is-dashed, .is-bad) — connectors; arrowheads via <marker> are auto-themed.
• .zaj-diagram-node (+ .is-core, .is-good, .is-warn, .is-bad) — labelled boxes (<rect rx="8"> + <text> / .sub).
• .zaj-diagram-annotation, .zaj-diagram-legend, .zaj-diagram-brain-*, .zaj-diagram-chip — callouts, legends, and the authority motif.
• .zaj-diagram-flow (ambient SMIL dots) / .zaj-diagram-packet + .zaj-diagram-node.is-active (click-to-play) — motion, auto-disabled under prefers-reduced-motion. See the gallery for the patterns.

Design tokens (app/src/styles/)

Never hardcode hex. Pull from these custom properties.

• tokens.css — brand palette, the single source of truth. Maps --zaj-* → Starlight’s --sl-*: --zaj-bg, --zaj-paper, --zaj-ink, --zaj-muted, --zaj-line, --zaj-strong, --zaj-accent, --zaj-accent-2, --zaj-accent-3, --zaj-good, --zaj-warn, --zaj-bad, --zaj-radius, --zaj-shadow.
• theme.css — the “paper-workbook” visual layer on top (--zaj-display, --zaj-grid, typography, hero, cards, .zaj-stepper, callouts).

Topic-first content tree

Top-level sidebar topics are set in app/astro.config.mjs. Every published doc lives under a subject path first, then the reader-intent shelf and kind:

app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/...

Segment	Holds	Example
<category>	Broad subject family	tech-stack, infrastructure, zajlibrary
<subcategory>	More specific area	laravel, hosting, authoring
<topic>	One canonical topic bundle	codecanyon, shared-hosting, content-system
<shelf>	Reader intent	learn, build, resources
<kind>	Doc type folder	guides, playbooks, templates, reference

The /browse/ page is the topic-first folder view. collection: still exists as metadata for legacy grouping and copy-as-prompt context, but it is no longer an active route family. Full IA rationale: Content architecture.

Copy as prompt

Every doc page includes Copy as prompt in the title bar and again at the page footer (wired via PageCopyPrompt.astro in PageTitle.astro + Footer.astro). The clipboard payload is assembled in app/src/lib/page-prompt.ts:

Section	Contents
Metadata	title, public URL, category, subcategory, topic, shelf, kind, status, collection, description, tags
Instructions	How the assistant should treat the page (cite headings, honor callouts, respect draft/target status)
Body	Cleaned page markdown — MDX imports/exports and HTML comments stripped

Authoring implication: set frontmatter accurately; bookend long pages with :::start / :::next / :::summary; use clear ## sections so copied prompts stay scannable. Details: AI writing contract → Copy as prompt.

Canonical URLs only

Use full topic-first paths in links — e.g. /tech-stack/laravel/codecanyon/build/playbooks/setup-new/, /infrastructure/hosting/shared-hosting/learn/guides/setup-shared-hosting/, /zajlibrary/authoring/content-system/resources/reference/writing-style/. Old shelf-first and collection aliases are not redirected; fix the link at source.

AI authoring layer (this repo)

What an agent has when working in this repo. Generic catalog of the concepts lives in AI Coding Agent Setup Reference; the below is this repo’s actual wiring.

Layer	Item	Purpose
Skill	content-intake	Universal inbox/enrich orchestration — file-by-file loop, ledger, multi-extract. .claude/, .cursor/, .agents/, .codex/skills/.
Skill	starlight-content-author	Platform shell — visuals, build, shelves, type router. .cursor/, .claude/, .agents/, .codex/skills/.
Skills	types/type-* (17)	Doc-type spines aligned to page templates — dispatch via content-intake. Map: .agents/skills/types/README.md.
Skill	specialized-codecanyon-laravel	CodeCanyon Laravel routing, skip buckets, collection rules. Legacy stub: codecanyon-content.
Agent	inbox-organizer	Review / organize / structure _INBOX/1-New/ — v2 loop + mandatory COVERAGE rows; closes slices to _Sources/; never publishes raw dumps.
Agent	doc-build-verifier	Runs the production build in isolation; reports green/red + the exact failure.
Rule	00-identity	Identity + read-order; loads at session start.
Rule	02-archive-not-delete	Never hard-delete — move losers to _Sources/<category>/<subcategory>/<topic>/.
Rule	03-inbox-first	Run the inbox pipeline when material is dropped.
Command	intake	Structure raw _INBOX material into published docs + close to _Sources/.
Archive	_Sources/<cat>/<sub>/<topic>/	Closed intake slices (ledger, indexes, plans, originals). WIP only in _INBOX/2-Research/.
Hook	check-inbox (SessionStart)	Surfaces unprocessed _INBOX/1-New/ files (read-only).
Cursor rules	stack · content-authoring · deploy	Always-on stack, content-glob authoring rules, deploy/DNS guidance.

Visuals decision rule (mandatory — full text in AGENTS.md)

Pages are not limited to prose + Mermaid. Pick the lightest tool that clears the bar:

1. Mermaid fence — generated boxes-and-arrows; works in plain .md.
2. Custom inline-SVG .astro component (components/diagrams/) — REQUIRED for bespoke editorial diagrams (architecture maps, boundary / ownership graphs). Quality bar: _Sources/resources/visuals/Mastra-LLM-SaaS-Architecture.html.
3. Image (src/assets/) — raster/photographic only, via astro:assets <Image>.
4. Framework island — only when runtime interactivity exceeds vanilla JS.

Any custom SVG/component MUST: theme via tokens.css (currentColor / var(--…), never hardcoded hex; correct in light and dark), be responsive (viewBox, no fixed pixel size), and be accessible (role="img" + <title>/<desc> via aria-labelledby). See AGENTS.md → “Custom visuals & components” for the binding rule and pre-publish gate.

Related

• Reusable Doc Components — live gallery of the diagram components + copy-paste recipes.
• How to write here — Writing Style — the enforced voice + QC checklist.
• Best Starlight Plugins — By Purpose — the wider catalog to pick future additions from.
• Starlight plugins in use — complete installed-package inventory (ops / system reference).