Skip to content

AGENTS.md

Latest commit

 

History

History
59 lines (46 loc) · 5.11 KB

AGENTS.md

File metadata and controls

59 lines (46 loc) · 5.11 KB

AGENTS.md

Guidance for AI coding agents working in this repository. Loaded into agent context — keep concise.

Overview

cadence-lang.org is the Docusaurus v3 documentation site for the Cadence smart contract programming language (Flow network). Content lives in docs/ as Markdown/MDX, rendered by Docusaurus with Code Hike for syntax-highlighted code blocks and an optional Typesense search index. Deployed at https://cadence-lang.org.

Build and Test Commands

Node 20.x required (package.json engines.node).

  • npm i — install dependencies
  • npm run start — local dev server at http://localhost:3000
  • npm run build — production build into build/ (used by CI)
  • npm run serve — serve the built site
  • npm run clear — clear Docusaurus caches (.docusaurus/, .cache-loader/)
  • npm run swizzle — swizzle a Docusaurus theme component
  • npm run write-translations / npm run write-heading-ids — Docusaurus i18n / heading-id maintenance
  • npm run deploy — docusaurus deploy (GitHub Pages); production deploy is actually driven by Vercel

No test suite is configured — there are no test scripts in package.json. CI (.github/workflows/deploy.yml) validates changes by running npm run build on push to main.

Architecture

  • docusaurus.config.js — single source of site config: navbar, onBrokenLinks: "throw", versioned docs (current labeled "1.0"), JSON-LD headTags (Organization, WebSite, ComputerLanguage, FAQPage), conditional Typesense theme, Code Hike remark plugin (Nord theme, line numbers, copy button), optional GTAG analytics, scripts: ['/hotjar.js'].
  • sidebars.js — one autogenerated sidebar (docSidebar) over the entire docs/ tree; ordering is driven by _category_.json files inside each docs subfolder.
  • docs/ — all documentation content:
    • language/ — Cadence language reference; subdirs accounts/, operators/, types-and-type-system/, values-and-types/
    • tutorial/ — numbered tutorial pages (01-first-steps.md through 09-voting.md)
    • cadence-migration-guide/ — Cadence 1.0 migration content
    • top-level pages: anti-patterns, design-patterns, security-best-practices, solidity-to-cadence, testing-framework, contract-upgrades, json-cadence-spec, project-development-tips, measuring-time, why, index
  • src/ — site code (React):
    • pages/ — custom routes (index.js, community.js) plus JSON content files consumed by them
    • components/ — HomepageFeatures/, Details/, feedbackFaces.tsx
    • theme/ — swizzled Docusaurus components: Admonition/, AnnouncementBar/, Details/, DocCard/, Layout/, TOC/, MDXComponents.js, NotFound.js
    • ui/design-system/, css/custom.css, utils/gtags.client.ts
  • static/ — copied verbatim to build root: favicon.ico, fonts/, img/, llms.txt, robots.txt, hotjar.js (loaded via the scripts field in docusaurus.config.js)
  • versions.json — ["current"]; only the live version exists, labeled "1.0" in config. No archived versions — don't run docusaurus docs:version unless intentionally branching.
  • vercel.json — URL rewrites/redirects (e.g. legacy /docs/1.0/* → /docs/*, /docs/language/<type-page> → /docs/language/types-and-type-system/<type-page>). Update here when moving pages.
  • .github/workflows/deploy.yml — on push to main, build check + Typesense scrape using docsearch.config.json. scrape.yml also exists in the same folder.

Conventions and Gotchas

  • Node 20.x is pinned (package.json engines; CI uses actions/setup-node@v3 with node-version: 20). Don't bump one without the other.
  • Docusaurus is pinned to 3.0.0 exactly (no caret). @docusaurus/core, @docusaurus/preset-classic, and @docusaurus/module-type-aliases must move together.
  • Broken links fail the build. onBrokenLinks: "throw" in docusaurus.config.js. When renaming a docs page, grep across docs/ and src/ and update references (or add a redirect in vercel.json).
  • Typesense search is env-gated. The theme only loads when both TYPESENSE_NODE and TYPESENSE_SEARCH_ONLY_API_KEY are set (see .env.example). Locally, search UI is absent unless those are set.
  • Code Hike is active on all docs code blocks (remarkCodeHike with Nord theme, lineNumbers: true, showCopyButton: true). Standard fenced code blocks work as-is.
  • Sidebar is autogenerated. Control labels and position via each folder's _category_.json, not by editing sidebars.js.
  • Tailwind scans src/**/* and docs/**/*.mdx only (tailwind.config.js content). Tailwind classes inside plain .md docs will not be generated — use .mdx if you need them.
  • URL redirects belong in vercel.json, not page front-matter. Follow existing patterns there when restructuring.
  • Licensing is split: source under Apache 2.0 (LICENSE.txt), content under CC-BY-4.0 (CC-BY-4.0.txt); see LICENSE.md.

Files Not to Modify

  • package-lock.json — regenerated by npm i
  • /node_modules, /build, .docusaurus/, .cache-loader/ — gitignored build artifacts
  • static/llms.txt — curated for LLM discovery; verify source before editing