Skip to content

CLAUDE.md

Latest commit

 

History

History
48 lines (36 loc) · 4.06 KB

CLAUDE.md

File metadata and controls

48 lines (36 loc) · 4.06 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Source for https://docs.openipc.org: the OpenIPC documentation site (open-source IP camera firmware, with a lot of FPV / WFB-NG material). It is an Astro 4 + Starlight 0.15 static site with Tailwind. There is no application code and there are no tests. Almost every change is to Markdown/MDX content.

Commands

Uses Yarn 4 (packageManager: yarn@4.0.2, nodeLinker: node-modules). The Node version is in .node-version (18.18.2); CI builds with Node 18.

yarn install
yarn dev        # local dev server (astro dev)
yarn build      # astro check && astro build -> dist/
yarn preview    # serve the built dist/
yarn format     # prettier --write . (prettier-plugin-astro)

yarn build is the only validation step. Run it before you consider a change done. astro check type-checks frontmatter against the Starlight schema, and some MDX mistakes only fail at build time. A missing component import, for example, renders without complaint in yarn dev but breaks the build.

Deployment: every push to main builds and deploys to GitHub Pages through .github/workflows/deploy.yml (withastro/action). CNAME and public/CNAME pin the custom domain.

Architecture

  • Content lives in src/content/docs/ as a single Starlight docs collection (src/content/config.ts uses the stock docsSchema()). The file path sets the URL. Every page needs title and description in its frontmatter, because description also feeds the OG image.
  • The sidebar is defined by hand in astro.config.mjs. It mixes two styles:
    • autogenerate directories pick up new files automatically: hardware/, software/, reference/, and use-cases/fpv/{net-cards,wfb-ng,apfpv}, use-cases/home-automation, use-cases/video-surveillance.
    • Explicit items lists in Getting Started, Development, Resources and the use-cases/fpv level itself. A new page in one of these sections must be added to astro.config.mjs, or it won't appear in the nav.
    • A new subdirectory under use-cases/fpv/ also needs its own sidebar entry.
    • Autogenerated groups sort alphabetically. To pin a page first, set sidebar: { order: 1 } in its frontmatter (the quick-start.md pages do this). Don't prefix the filename with a dash: the dash stays in the URL.
  • The landing page is getting-started/homepage.mdx. / redirects to it (see redirects in astro.config.mjs). There is no index.mdx, because the redirect would hide it anyway.
  • OG images: src/pages/og/[...slug].ts uses astro-og-canvas to render a PNG for every docs entry from its title and description. src/components/Head.astro overrides Starlight's Head to inject the og:image and twitter:image meta tags.
  • Custom components in src/components/ are imported from MDX pages:
    • ThemeImage.astro takes lightSrc, darkSrc and alt, and swaps the image for light or dark theme.
    • wfb-calculator.astro is the WFB-NG bitrate calculator used by wfb-ng-calculator.mdx.
    • roadmap.astro, card.astro and card-grid.astro.
    • Starlight's own Card and CardGrid from @astrojs/starlight/components.

Content conventions (from development/contribution-guidelines.md)

  • New filenames should be lowercase kebab-case, because the filename becomes the URL. Some existing files don't follow this (e.g. APFPV.md, Greg's_APFPV.md, hardware/EMAX/...); don't rename them casually, since that breaks their URLs.
  • Use .mdx only when the page imports components. Put the imports right after the frontmatter, using the absolute-from-root form: import ThemeImage from '/src/components/ThemeImage.astro'.
  • Images go in public/images/ and are referenced as /images/<file>. Downloadable files go in src/assets/files/.
  • Use Starlight asides (:::note, :::caution, :::danger, :::tip) for callouts.
  • Mark unfinished sections with a badge: { text: "WIP", variant: "caution" } entry in the sidebar config.
  • Every page gets an "Edit page" link that points to github.com/OpenIPC/docs/edit/main/.