Skip to content

Development guide

Where source files live and how to develop pages, components, and exports.

Updated View as Markdown

Develop the site from its source files. Preserve the calm reading experience. Keep the content equally usable for people and agents. This guide defines development practices. It does not authorize deployment or changes to external services.

Read the repository files AGENTS.md and README.md first. Use Content standards for writing. Use Maintenance and upgrades for checks and updates. For technical model pages, also read the Model Deep Dive guide and adapt its starter template.

Source map

Location Purpose
src/content/docs/ Published learning pages and guidance
src/content/docs/about/content-guidance/ Writing standards, study guides, and templates
src/content/docs/about/ Site purpose, framework, development, and maintenance
src/content/partials/ Reusable Markdown or MDX content
src/content.config.ts Content collections and schemas
src/components.ts Components available globally in MDX
src/components/ Shared interface and local components
src/components/ui/ Components copied from the Nimbus registry
src/layouts/ Page shell, navigation, and reading layout
src/styles/ Shared styles and Latent Light additions
src/pages/ HTML routes, text exports, agent indexes, and social images
astro.config.ts Sidebar, integrations, rendering, and canonical origin
nimbus.json Nimbus provenance and reviewed upgrade baseline
.node-version Shared Node version for local development and automated builds
.github/workflows/validate.yml GitHub validation without deployment credentials
wrangler.jsonc Production Worker, domain, and static asset configuration
scripts/verify-deployment.mjs Public checks after deployment
public/ Assets included in the published build
docs/branding/ Asset references and generation records
docs/research/ Public-safe evidence, provenance, and review records
.agents/skills/latent-light-deep-research/ Versioned research skill, schemas, tools, and tests

Do not edit files in these directories:

  • dist/ contains build output.
  • .astro/ contains generated Astro files.
  • node_modules/ contains installed dependency files.
  • .wrangler/ contains local Cloudflare state.

Build and development tools manage these files.

Add or update a page

Create a Markdown or MDX source in src/content/docs/. Set title, description, and lastUpdated in frontmatter, the metadata block at the top of the file. The content schema requires title. The layout uses title as the page heading.

Add each new page to the explicit sidebar in astro.config.ts. Link related explanations. Preserve established URLs. Use a redirect when replacing a route.

Organize learning collections under broader domains. AI Technology contains LLM & VLM, Document AI, Knowledge Distillation, Agents, Local & Cloud AI, Hardware 101 and Edge AI. Products & Markets contains AI Landscapes. Human Capabilities contains High agency and Taste. Do not add empty navigation groups. A sidebar grouping change does not require moving source files or changing page URLs.

Use <Render file="partial-name" /> for reusable content from src/content/partials/. Do not import MDX files directly into other pages. Register shared MDX components in src/components.ts. Alternatively, import a component explicitly in the page that uses it.

Work with Nimbus components

Use PascalCase component names. Use the Nimbus installer for existing registry components. Do not recreate those components manually. Review dependencies and changed files before retaining the result.

npx --no-install @cloudflare/nimbus-docs list
npx --no-install @cloudflare/nimbus-docs add COMPONENT_SLUG
npx --no-install @cloudflare/nimbus-docs add FEATURE_SLUG --print

Replace each uppercase placeholder with a reviewed registry slug. A slug is the registry identifier for a component or feature. add can copy files and install dependencies. Feature recipes describe changes for the developer to adapt.

Review the exact replacement before using --overwrite on customized files. See the Nimbus CLI documentation.

Use Nimbus’s Icon component with Phosphor icons. The import path is @cloudflare/nimbus-docs/components/Icon.astro. Icon names use the ph: prefix.

Preserve reading and editing behavior

Keep the left navigation, central article, and right outline on desktop. Preserve independent sidebar collapse, focus view, and reading preferences across navigation. Mobile uses a drawer and section selector. Keep the browser title as Latent Light. Keep the Astro developer toolbar disabled.

Put project styling in src/styles/latent-light.css where practical. Avoid rewriting Nimbus components solely for a small feature specific to this site. Initialize client handlers after page navigation. Remove obsolete listeners.

For wide visuals, import src/components/FocusCanvas.astro in the page. Use its label and size props. Available sizes are figure, diagram, and wide. Only the visual should expand in focus view, not the reading column. Keep a meaningful text equivalent in the exported content.

Follow the figure numbering and caption standards. SourceFigure and FoundationDiagram accept an id for figure anchors. Keep caption labels in the page source so the text export retains them. Import SourceFigure and ModelFlow explicitly in pages that use them. They are not globally registered.

Keep sourceFigureAsMarkdown from plugins/source-figure.mjs registered in astro.config.ts. It preserves the image, numbered anchor, meaningful description, complete caption and citations while removing the image-slot presentation wrapper. Its regression tests run with npm run test:content.

For dense report figures, set SourceFigure’s optional minWidth to a readable width in pixels. Desktop shows the complete image; smaller screens preserve that readable width and pan within the figure frame. The frame supports keyboard scrolling and has a full size link. Check both normal and focus view; do not let a wide image expand the whole page. Extract a high resolution source crop that retains every label, legend, axis and arrow. Record its page, figure number, crop, source version and reuse basis in the research records. Follow the paper figure reuse standard.

For an overview poster, add zoomable fitInitially with minWidth. The full image fits the frame on every screen until the reader selects Enlarge labels. The enlarged image pans within its frame, including with the keyboard. Keep a text equivalent beside the figure and retain the full size link.

For generated figures with light and dark artwork, keep the primary image in the Markdown image slot of SourceFigure and pass the matching asset as darkSrc. The figure and full size link follow the page theme without a client script. Print uses the light version. Keep the same content and text equivalent in both images; do not convey meaning through color alone.

For an animated figure, give SourceFigure an id, the still src and an optional motionSrc. Keep the still in its Markdown image slot; the Markdown exporter also links to the animation. In the page, the image opens the full-size still, without a toolbar or playback buttons. Omit minWidth and zoomable for this presentation. Hardware 101 uses a continuous loop, as requested by the user, without visible playback controls. Playback runs with JavaScript while the image is in view, the tab is visible and reduced motion is not requested. Reduced motion, no JavaScript and printing use the still. Keep all essential labels stable and preserve the complete meaning without playback. Animated figures currently use one artwork variant rather than darkSrc.

The local source editor exists only in development mode. The Edit source button opens a full height pane below the header while keeping desktop navigation available. The pane follows sidebar collapse and focus view. It opens at the section currently being read, with a cursor positioned at the matching source heading. Generated References opens at the footnote definitions.

The header identifies the page and source path. Save page writes to the local working tree and refreshes the page; it does not commit, push, or deploy. Use Ctrl+S or Cmd+S to save and Escape to close. Reload source and closing the pane require confirmation before discarding edits. Navigation and refresh warn about unsaved changes. Preserve these protections:

  • Loopback binding restricts the server to the local computer.
  • Same origin checks restrict requests to the editor’s origin.
  • Path checks restrict the files that the editor can access.
  • Revision conflict protection prevents edits from silently replacing newer changes.

Keep the editor absent from production builds and preview. Edit only trusted MDX because MDX can execute code during rendering.

Development and validation use separate Vite caches. Preserve this separation. A build must not invalidate dependencies in a running local server.

Keep agent exports complete

Preserve these parts of the export system:

  • <AgentDirective /> in BaseLayout.astro
  • The alternate Markdown link in the page head
  • /llms.txt and /llms-full.txt
  • The Markdown and MDX page routes

Do not edit generated exports separately from the page source.

Check custom components in HTML and Markdown. Preserve essential examples, citations, captions, assumptions, and media explanations. Extend Markdown processing through the Nimbus plugin configuration. Review compatibility before replacing the processor.

For model flow diagrams, use ModelFlow.astro with a static lanesJson attribute containing JSON. Use a single quoted attribute; encode apostrophes and angle brackets inside JSON strings as Unicode escapes. Do not use nested JavaScript expressions for exported diagram data. The modelFlowAsMarkdown transform emits ordered steps, lane notes, feedback descriptions, and the cited caption. Its regression tests run with npm run test:content. Desktop flows read left to right; narrow reading widths stack the same steps vertically.

For company explorers, import ResearchTable from src/components/landscapes/ResearchTable.astro and place a native Markdown table inside it. Wrap the component in FocusCanvas when the comparison is wide. The category column is zero-indexed and defaults to the second column. Search, filter and reset enhance reading only; the table stays visible without JavaScript. The researchTableAsMarkdown transform in plugins/research-table.mjs preserves all rows and citations without the controls. Test filters, keyboard scrolling, print output and full text exports when changing the component.

Company explorer icons are an HTML reading aid. plugins/company-icons.mjs adds a reviewed local 24 px mark beside the first company link, without changing the native table source or Markdown export. The shared registry is src/data/company-icons.json; sources, checksums and reuse assessments are in docs/branding/company-icons.json. Match the company or product actually named in the row, never an accelerator, hosting provider or unrelated namesake. Use initials when identity or reuse is unresolved. Keep marks unchanged in color, preserve text names and links, hide redundant images from assistive reading, and check both themes, mobile panning, no JavaScript and failed-image fallback. Use local files, not a third party logo service or runtime hotlinks.

For product and industry maps, use LandscapeMap.astro with a static cardsJson attribute. Each card has label, role, examples, and question text. Its Markdown exporter retains every field, the figure anchor, notes and cited caption. The responsive cards use words as well as color to identify their roles. Keep ranking, measured outcomes and proposed questions distinct. Regression tests run with npm run test:content.

For shared architecture mechanisms, use ArchitectureAtlas.astro. Supply a static kind from plugins/architecture-atlas.mjs and a stable figure id. Each panel has a native SVG and a complete visible text explanation. Keep the explanation, assumptions and figure caption meaningful without the SVG. The architectureAtlasAsMarkdown transform exports that same text. Add tests when you add a mechanism. Check small reading widths, dark mode and focus view; do not make labels readable only in an expanded view.

Model studies begin with ModelResources cards. Use static reportHref, modelHref, and modelName attributes. modelHref points to the Hugging Face repository root, not a file or revision. The resource exporter preserves both links and their labels in Markdown. Keep exact artifact versions in research records and immutable reference URLs rather than displayed hashes.

Use native Markdown footnotes as specified in the citation standards. The local plugin plugins/reference-heading.mjs makes the generated References heading visible without replacing Nimbus’s processor. It preserves citation anchors and return links. Renderer regression tests run through npm run test:content and are part of npm run validate.

Comparison tables

Use src/components/ComparisonTable.astro for general comparisons. Keep the content in a native Markdown table inside the component. Set id, title and an accessible label. Use itemLabel for the row count, such as models or products. Add the optional search attribute only when a catalog benefits from search.

The component adds column headers and pinned row headers without changing cell content. It supports keyboard scrolling, result counts, reset and an empty state. All rows remain available without JavaScript, in print and in Markdown exports. Use ResearchTable for company directories that need category or base filters.

Wrap wide comparisons in FocusCanvas with size="wide". Keep comparisonTableAsMarkdown registered in astro.config.ts. Its implementation lives in plugins/comparison-table.mjs. Check search, pinned labels, keyboard scrolling, print and complete exports after changes.

Hardware foundation figures and budgets

src/components/hardware/HardwareFigure.astro renders the system, circuit, sampling, chip, memory and timing figures on Hardware 101. Pass a static kind and numbered figure id. Its shared content and complete text equivalent live in plugins/hardware-foundations.mjs; keep hardwareFigureAsMarkdown registered in astro.config.ts. The signal plot uses original mathematical samples, not measured sensor data. The circuit is an ideal DC example; the timing plot uses explicitly assumed stage durations and dedicated resources. Chip, memory and timing diagrams pan at narrow widths, including with the keyboard. The board map emphasizes containment; the memory diagram shows one staging path with access exceptions, and timing brackets distinguish per-frame latency from completion intervals. The figures inherit the site’s Inter font and theme tokens, with one amber focal category and neutral supporting marks. Keep circuit symbols and plotted data faithful when applying diagram-design’s layout guidance. Preserve every label, duration, boundary and assumption in their shared text exports.

HardwareBudget.astro uses plugins/hardware-budgets.mjs for shared input definitions, unit calculations, initial results and Markdown exports. Keep hardwareBudgetAsMarkdown registered. Inputs enhance the static examples; invalid or empty values must produce an understandable error, not a result. Check keyboard calculation selection, editing and reset, both themes, Focus view, narrow screens, the no-JavaScript examples, print and complete exports after changes. Calculator and export checks run with npm run test:content.

The Document AI system map

src/components/DocumentSystem.astro renders the fixed overview on the Document AI page. Its five functional layers are Documents, Perception, Representation, Understanding and Action. The figure also shows preserved artifacts, reliability checks and reviewed feedback. It describes a proposed system, not five required model calls.

Edit the shared documentSystem data in plugins/document-system.mjs when the figure’s meaning changes. The component and documentSystemAsMarkdown use that same data. Keep its numbered caption in the page source. Use FocusCanvas with size="diagram" for the complete horizontal view. Narrow layouts must retain the path through all five layers and readable text. Use ModelFlow for other flows rather than copying this fixed system map.

Document model family atlas

DocumentModelAtlas.astro renders the dated family map on Document AI. Import it explicitly, supply a numbered figure id, and wrap it in FocusCanvas. Keep the caption in the page source. The milestone data, typed relationships and complete Markdown equivalent share plugins/document-model-atlas.mjs.

A milestone identifies its report revision, release log, announcement or explicitly labelled benchmark snapshot; it does not silently establish first weight availability. Keep family/design updates separate from explicit checkpoint initialization. Lanes are overlapping themes. Date and relationship evidence lives with the Document AI research records.

Keep documentModelAtlasAsMarkdown registered in astro.config.ts. Check native keyboard selection, model/study/source links, both themes, responsive reflow, the no-JavaScript map and complete text exports after changes. The expanded timeline uses measured node positions; narrow layouts retain dates and explicit text connections without shrinking a poster.

Agent maps and navigation cards

Use the components in src/components/agents/ for the Agents collection. Their shared data parsers and Markdown renderers live in plugins/agent-presentation.mjs. Supply static JSON text rather than JavaScript expressions.

  • AgentCards.astro provides navigation cards. Give cardsJson an array with title, description and an Agents page href. An optional eyebrow adds a short label.
  • AgentArchitecture.astro presents system layers. Give layersJson an array with label, detail and parts. Each part contains a title and body. Optional subtitle and footer text must survive the export.
  • AgentLandscape.astro presents the collection overview. Its mapJson includes human intent, the work loop, capabilities, controls, system families and frontier questions. Follow the schema that readAgentLandscape checks rather than inventing new fields.

The two figure components require a numbered figure-N anchor and an authored caption. Wrap wide figures in FocusCanvas. Preserve all descriptions, assumptions, feedback, links and citations in Markdown. Keep agentCardsAsMarkdown, agentArchitectureAsMarkdown and agentLandscapeAsMarkdown registered in astro.config.ts. The regression checks run in scripts/agents-content.test.mjs.

Present short videos

Use src/components/media/VideoGallery.astro for a small collection of related clips. It presents one large portrait player and a list of clips beside it, with a stacked layout on narrow screens. Import it explicitly in the page. Provide stable IDs, YouTube IDs, titles, durations, descriptions, local WebP posters and transcript anchors in a static videosJson attribute.

Keep the AI generation disclosure, attribution and complete transcripts in the component’s content slot. Native details elements can keep transcripts compact. The player loads after a reader selects Play or a clip; switching or closing removes the previous iframe. Links to YouTube remain usable without JavaScript. The iframe uses the Nimbus registry Embed component.

Keep videoGalleryAsMarkdown from plugins/video-gallery.mjs registered in astro.config.ts. Check that exports retain every clip’s link, duration, description and transcript. Store media provenance with the topic’s research records and keep full audio and video files outside the public source assets.

Jensen’s edited clips

The standalone Jensen collection uses JensenClips.astro for square MP4 excerpts. Keep one native player beside a compact directory, with search, theme selection and six entries per page. Stack the player above the directory on phones. Do not turn a growing clip collection into an unbounded card grid or an infinite feed. Selection and directory filtering are independent; changing a directory page must not interrupt the active clip. Pause short clips when a full conversation starts, and close the conversation player when a short clip starts. Load video only after a reader chooses to play.

Maintain clip titles, source timestamps and release metadata in src/data/jensen-clips.json. HTML and the Jensen Markdown export use the same catalog and preserve complete caption transcripts. An X post is not a reuse clearance record. A release needs a documented reuse basis, reviewed media on media.latentlit.com, captions and a complete transcript before it appears in a production build.

The developer preview prefers the catalog’s named files from ignored output/jensen-clips/, then falls back to published release URLs. Unreleased clips with missing local media are skipped so a fresh checkout remains usable. Use anonymous CORS on the native player so external caption tracks can load. Keep the original contextual note beside each transcript and in Markdown exports. The development-only media middleware accepts loopback hosts, same-origin requests and read-only byte ranges. It must not be installed in production or expose arbitrary files. Keep unreleased MP4s, posters and captions outside public/ and Git. Test range handling, publication gating and directory pagination with npm run test:content.

Present a podcast

Import src/components/media/PodcastPlayer.astro for hosted audio. Supply a stable ID, title, published MP3 URL, duration and transcript anchor. Keep the generation disclosure and attribution in its content slot. Use native audio controls; playback starts on the reader’s choice. JavaScript adds speed selection and pauses overlapping media. Native controls and source links work without it.

Keep the full transcript in authored content. Label automatic transcriptions accurately and record their method with the media provenance. Hosting settings and delivery checks live in docs/media/; recording originals stay outside Git.

Register podcastPlayerAsMarkdown from plugins/podcast-player.mjs in astro.config.ts. Exports must retain the source link, duration, disclosure and transcript. Verify real playback, seeking and speed controls, along with keyboard use and narrow-screen rendering.

Render mathematics

Author math using the equation standards. astro.config.ts selects Astro’s native Sätteri processor with math: true. Nimbus still supplies its admonitions and normal Astro rendering passes. The existing table and reference plugins remain in the same pipeline.

plugins/math-typesetting.mjs typesets native Markdown math nodes with KaTeX at build time. MDX pages use the globally registered MathExpression component because Nimbus’s source scanner does not recognize math delimiters. Pass LaTeX in a static tex attribute and add display and number="1" for a standalone equation. The component adds \tag{1}; do not also put a tag in its tex value. Numeric tags produce an equation-1 anchor and an accessible equation label. Both paths produce visual HTML and accessible MathML with a TeX annotation. Invalid LaTeX fails the build. Trusted HTML commands are disabled, and macros do not carry between expressions. Code examples and quotations remain literal.

BaseLayout.astro imports KaTeX CSS. Its fonts are bundled locally; no CDN or client side renderer is used. Equation styles in src/styles/prose.css keep display formulas centered, with right aligned numbers and symmetric space to prevent overlap. Wide formulas and their numbers stay in a keyboard accessible scrolling region. Keep those styles scoped to article content. Do not apply code or quotation styles to equations.

KaTeX and the Sätteri processor are explicit dependencies. The rendering tests in scripts/math-typesetting.test.mjs run through npm run test:content. Check actual pages in both themes and at narrow widths. Confirm that Markdown exports retain the standard dollar delimiters, notation, equation tags, and citations. The mathAsMarkdown component transform in astro.config.ts supplies this conversion. MDX exports retain the original component and LaTeX attributes. Neither export should contain rendered spans or stripped equations. KaTeX documents its rendering options.

If replacing Sätteri, set admonitions: false. Preserve the existing callout behavior. See the Nimbus endpoint documentation.

Research workflow and tools

Use the Research workflow for substantial investigations. The repo-local latent-light-deep-research skill coordinates that workflow. Read its SKILL.md and applicable references before using its tools. It needs Python 3.10 or newer and no third-party Python packages.

For new site research, the MD or MDX page is the canonical narrative. Keep evidence and actual review results in docs/research/<domain>/<topic>/; do not maintain a second article in report.md. A requested standalone report can be the canonical output instead. Preserve existing schema 2 reports and records without automatic migration.

The skill initializer creates records, not page content. Its validator reads records without modifying them. Neither tool establishes scientific truth, visual quality, or reuse rights. When changing the tools, run npm run test:research as well as the relevant site checks.

Retain source and asset records

A canonical link is enough for an ordinary citation. Keep a concise record in docs/research/<topic>/ for a closely studied paper or a source that supplies a visual. Use docs/branding/ for identity assets. These records support the Content standards. They do not duplicate the editorial guidance.

Record these details for each source:

  • Title and author or organization
  • Canonical URL
  • Exact version or publication date
  • Retrieval date

For changing information, distinguish the source date from the date you checked the claim.

For a reproduced or adapted visual, also record these details:

  • Figure number or location in the source
  • Copyright holder and applicable usage terms, including third party exclusions
  • Reuse basis: license, direct permission, or a documented applicable exception
  • For an exception: purpose, distribution, amount, alternatives, nature, likely effect and remaining uncertainty; do not label it as a license grant
  • Extraction or adaptation method
  • Resulting asset path

Retain prompts and reference provenance for AI generated assets. Keep a useful caption and source link on the page, not only in the repository record.

If a local paper copy helps study, preserve the original version unchanged. Record its filename and checksum to distinguish it from later versions. Do not commit or deploy complete downloaded papers merely because selected figures can be reused. Assess each excerpt for its intended public distribution under the reuse standard. Local study archives can remain outside the public repository.

Use src/assets/ for page visuals that Astro processes. Use public/ for assets that need stable paths. Prefer SVG or HTML for original technical diagrams when practical. Include accessible descriptions. Preserve the meaning of visuals at narrow widths and in text exports. Keep large media outside the source repository.

Repository records are also intended for public sharing. Do not place private research notes, confidential sources, or restricted files in these records. The absence of a permissive artwork license is not an automatic rejection. If neither a license, permission nor a defensible exception supports the intended use, link to the source or write an independent explanation.

Visual identity and provenance

The identity uses Echo, two offset lightning bolts in gold and orange. Preserve the complete silhouettes and transparent gap between the bolts. Keep the established public/brand/logo-dark.png and public/brand/logo-light.png paths. Both currently contain the same transparent 1254 by 1254 pixel artwork, which works in either theme. The header switches between these complete images with the theme. The selection, exact generation prompts and asset checksums are recorded in docs/branding/identity.md and its linked concept records. The PNGs are raster artwork, not vector masters.

public/favicon.ico contains 16, 32, 48, 64, and 256 pixel versions of Echo. Its source is public/brand/favicon-master.png, the same transparent artwork used for the theme logos. Generate the icon sizes from that master without changing the mark’s proportions. The homepage uses public/brand/galaxy-line-art.png as original AI generated decorative artwork. This artwork is not an astronomical diagram.

Keep the artwork static. Adapt it to the theme. Hide it when printing. Do not add a large logo to the homepage body.

The small author introduction uses public/brand/avatar-bingyuan-cartoon.png. This AI generated cartoon uses the author’s public portrait as a loose reference. Its source link and generation prompt remain in docs/branding/avatar-cartoon.md. Keep license records in THIRD_PARTY_NOTICES.md and public/licenses/.

Before completing a change, follow the validation checklist.

Landscape overviews and collection accents

Use LandscapeOverview.astro for a numbered opening overview image. It reuses SourceFigure for full-resolution access and mobile panning. Register its Markdown renderer so the figure anchor, image, alt text and cited caption survive exports. Keep an equivalent explanation or comparison table in the page; the image must not be the only source of essential information. Save generation prompts and review notes with the research records.

LandscapeCards.astro adds local, restrained accents to the landscape hub’s Nimbus cards. Keep the change scoped to that collection and preserve semantic links, keyboard focus, theme contrast, responsive layout and text exports.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close