lapis.md Site (@lapis-notes/lapis.md)

The lapis.md package is the deployable public documentation and marketing site for Lapis Notes. It serves the landing page, end-user help, and plugin developer docs as static HTML at https://lapis.md.

Source: packages/lapis.md/

Responsibilities

• Builds a static Astro + Starlight site with dual doc trees at /help/ and /developers/.
• Generates a TypeScript API reference under /developers/api-reference/ from the curated packages/api/src/lib/docs-api.ts entry point before Astro dev/build/check, preserving source-driven descriptions and Forgejo Defined in links for the published plugin API.
• Provides a custom marketing landing page at / with CTAs to the app, help, and developer sections.
• Publishes top-level legal pages at /privacy/, /terms/, and /license/, linked from the shared site header/footer and the Starlight docs header.
• Uses a shared Obsidian-style multi-column site footer pinned to the page bottom on the landing and legal shells only; Help and Developer docs pages with sidebars omit it.
• Top header nav links highlight the active section with a dark surface pill and matching ink text.
• Narrows the desktop docs On this page rail to 18.75rem (~300px) with a custom PageSidebar.astro override so Starlight’s default viewport-percent TOC width does not expand the rail on wide screens.
• Renders a starlight-site-graph interactive graph above the desktop docs On this page rail for /help/ and /developers/ pages, using the package’s sitemap generation while preserving the site-local PageSidebar.astro override. Generated /developers/api-reference/ pages are excluded from graph data and hide the graph panel because they are not graph nodes, keeping the Developer docs graph focused on authored guide pages.
• Treats /help/ and /developers/ as first-class docs home pages inside the normal three-column docs shell instead of Starlight splash pages, so the left nav, center article, and right TOC appear immediately on load.
• On wide Help and Developer docs pages, spare horizontal space is split into outer margins on both sides through --lapis-page-gutter, a custom TwoColumnContent.astro override, and matching shifts in PageFrame/header padding so the left nav, article, and TOC sit in a centered three-column shell instead of hugging the viewport edges. The /help/ and /developers/ home pages keep the same centered shell and additionally drop the usual header bottom border.
• Applies an Obsidian-aligned public-site light/dark token map in src/styles/lapis-starlight.css, matching the app’s canvas, violet accent, hairline border, and compact radius language without importing app runtime CSS.
• Uses the Lapis logo SVG as the site favicon at /favicon.svg.
• Exposes root orchestration scripts: dev:site, build:site, and preview:site.
• Produces a dist/ artifact for static hosting; DNS target for docs is separate from app.lapis.md.

Technology

Boot / Dev Surface

Local dev

pnpm dev:site

Build

pnpm build:site

The site package is self-contained for public-site styling and does not need the UI package to prebuild before Astro bundles styles.

Content Model

• Landing — src/pages/index.astro with shared SiteLayout.astro header/footer and generated product-evidence captures for editing, markdown/graph/canvas views, bases, plugins, notebooks, tasks, slides, search, and PDF. The lower markdown/graph/canvas and bases/plugins/notebook sections stack three full-width landing-band rows with large landing-shot--feature frames rather than a multi-column card grid.

• Legal pages — src/pages/privacy.astro, src/pages/terms.astro, and src/pages/license.astro use SiteLayout.astro and the site-local legal prose styles. They publish current-state policy text for local-first privacy, terms of use, package licensing, third-party notices, and trademark boundaries. Legal links appear in the landing/legal header and footer, and StarlightHeader.astro adds the same links to the desktop docs header.

• User help — src/content/docs/help/** (getting started, VS Code-inspired UI layout/shortcut guidance, notes, a comprehensive editing reference, screenshot-backed plugin pages including a multi-page Notebook subsection, desktop/web, import, support, and attributions). The /help/ landing page is a normal docs article inside the shared sidebars-and-TOC shell rather than a standalone splash page.

• Developer docs — src/content/docs/developers/** (plugin model, runtime overview, manifest, lifecycle, development workflow, App/vault/workspace/editor/events/metadata/notices/settings API surface, language and editor extensions, CSS contract, publishing, trust, and safe mode). The /developers/ landing page follows the same docs-shell treatment so plugin authors land directly in the main documentation layout.

  /developers/api-reference/ is generated from TypeDoc markdown through a site-local wrapper script that injects Starlight frontmatter, rewrites TypeDoc’s class pages from classes/ to class-docs/ for Astro route compatibility, and preserves repo source links back to Forgejo. The generated pages stay checked into the repo as normal site content and are refreshed explicitly with pnpm --filter @lapis-notes/lapis.md api-docs:generate. TypeDoc reads packages/lapis.md/typedoc.tsconfig.json, which extends the API dev tsconfig so first-party imports resolve from source and API reference generation does not depend on prebuilt dist/ artifacts.

  The Language & editor extensions section under /developers/language-extensions/ documents the public plugin surface for VS Code-inspired editing: CodeMirror/Lezer syntax registration, editor views and associations, LanguageServiceProvider, lapis.contributes manifest metadata, and CodeMirror extension registration. It maps those concepts from the VS Code language-extension model without documenting TextMate grammars, LSP wire protocol, or internal boot details.

The public site supports light, dark, and Default themes through Starlight’s theme toggle on docs pages and a matching control on the landing/legal header. Default is the initial selection on page load: the main site uses dark, while /help/ and /developers/ docs use light. Explicit light or dark choices persist in localStorage under starlight-theme across docs, landing, and legal shells via shared data-theme tokens in src/styles/lapis-starlight.css.

Public documentation content may adapt permissively licensed upstream documentation when attribution and license requirements are preserved on the site. Current attribution lives under Help and Support.

Public developer pages describe the supported plugin API only. Internal boot/runtime detail stays in spec/.

The public help docs may show syntax examples directly when Starlight can render them faithfully, but vault-aware markdown features that depend on the app renderer should be documented with syntax plus real captured app evidence rather than approximated by the site markdown pipeline.

Visual System

The public site uses an Obsidian-aligned software-documentation style with light and dark palettes:

• Dark: canvas #171717, card surface #1e1e1e, hairline #262626, ink #e5e5e5, muted ink #b3b3b3, accent #a78bfa, and filled action violet #8a5cf5.
• Light: canvas #ffffff, card surface #fafafa, hairline #e0e0e0, ink #222222, muted ink #5c5c5c, accent #7852ee, and filled action violet #6d47e0.
• Platform system UI and monospace font stacks only.
• Filled buttons use white text on violet. Sidebar active links use white text on #8a5cf5; inactive sidebar links use muted gray.
• Cards and screenshot frames use 1px hairlines, compact radii, and app evidence rather than decorative illustration.
• Docs code fences use Expressive Code with github-light and github-dark-dimmed themes on --lapis-surface-1 backgrounds, switching with the site theme.
• The Help and Developer docs graph maps starlight-site-graph variables to the active Lapis token set and the bundled graph plugin’s subdued node/link language without importing app runtime CSS. Hovered labels use the primary violet separately from highlighted links, base labels stay compact for the sidebar, and fullscreen mode increases the graph scale to better use the expanded canvas.

Media Capture

• pnpm media:site prepares e2e-vault-temp, boots the workspace dev server, creates a fresh browser vault, seeds the tracked e2e-vault dataset into it, restores .obsidian/workspace.json, captures the landing hero from that default layout, and for each view-specific still runs Workspace: Focus Leaf (app:focus-leaf) before screenshotting the full .workspace shell.
• Generated assets live under packages/lapis.md/public/media/.
• Landing stills use predictable landing-*.png filenames; plugin/help stills use help-*.png including help-notebook-view.png, help-notebook-dependencies.png, help-notebook-packages.png, and help-notebook-variables.png; workflow motion assets use help-*.gif filenames.
• Keep still screenshots roughly 1280-1440px wide and keep animated GIFs short, dark-theme, and around 960px wide so the site ships optimized but readable media.

Domain Split

Deployment

Production hosting is Cloudflare Pages at https://lapis.md.

The publish workflow runs on pushes to main that touch packages/lapis.md/ or the publish workflow file. It checks the site package, builds static output, and deploys the prebuilt dist/ directory with Wrangler in the same job. Manual reruns are available through workflow_dispatch.

Forgejo repository secrets required for deploy:

• CLOUDFLARE_API_TOKEN — API token with Cloudflare Pages → Edit for the account
• CLOUDFLARE_ACCOUNT_ID — account ID that owns the Pages project

Create the Cloudflare Pages project named lapis-md, attach the lapis.md custom domain in the Pages dashboard, and point DNS at Cloudflare before the first automated deploy.

Production publication runs through Forgejo (.forgejo/workflows/publish-lapis-md.yml). Source code lives at code.ju.ma/lapis-notes/lapis.

Validation

pnpm --filter @lapis-notes/lapis.md check:all

Root pnpm check:all includes this package through Turbo. The site check runs pnpm --filter @lapis-notes/lapis.md api-docs:check before astro check; that non-mutating verification regenerates the API docs in a temp workspace, compares them against the checked-in src/content/docs/developers/api-reference/ tree, and fails on drift. TypeDoc still reads typedoc.tsconfig.json, which extends the API dev config so the docs pipeline resolves @lapis-notes/* imports from source and passes on a clean checkout without prebuilding UI or API dist/ output.

Troubleshooting