|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Guidance for AI coding agents working in this repository. Loaded into agent context — keep concise. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +`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. |
| 8 | + |
| 9 | +## Build and Test Commands |
| 10 | + |
| 11 | +Node 20.x required (`package.json` `engines.node`). |
| 12 | + |
| 13 | +- `npm i` — install dependencies |
| 14 | +- `npm run start` — local dev server at http://localhost:3000 |
| 15 | +- `npm run build` — production build into `build/` (used by CI) |
| 16 | +- `npm run serve` — serve the built site |
| 17 | +- `npm run clear` — clear Docusaurus caches (`.docusaurus/`, `.cache-loader/`) |
| 18 | +- `npm run swizzle` — swizzle a Docusaurus theme component |
| 19 | +- `npm run write-translations` / `npm run write-heading-ids` — Docusaurus i18n / heading-id maintenance |
| 20 | +- `npm run deploy` — `docusaurus deploy` (GitHub Pages); production deploy is actually driven by Vercel |
| 21 | + |
| 22 | +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`. |
| 23 | + |
| 24 | +## Architecture |
| 25 | + |
| 26 | +- `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']`. |
| 27 | +- `sidebars.js` — one autogenerated sidebar (`docSidebar`) over the entire `docs/` tree; ordering is driven by `_category_.json` files inside each docs subfolder. |
| 28 | +- `docs/` — all documentation content: |
| 29 | + - `language/` — Cadence language reference; subdirs `accounts/`, `operators/`, `types-and-type-system/`, `values-and-types/` |
| 30 | + - `tutorial/` — numbered tutorial pages (`01-first-steps.md` through `09-voting.md`) |
| 31 | + - `cadence-migration-guide/` — Cadence 1.0 migration content |
| 32 | + - 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 |
| 33 | +- `src/` — site code (React): |
| 34 | + - `pages/` — custom routes (`index.js`, `community.js`) plus JSON content files consumed by them |
| 35 | + - `components/` — `HomepageFeatures/`, `Details/`, `feedbackFaces.tsx` |
| 36 | + - `theme/` — swizzled Docusaurus components: `Admonition/`, `AnnouncementBar/`, `Details/`, `DocCard/`, `Layout/`, `TOC/`, `MDXComponents.js`, `NotFound.js` |
| 37 | + - `ui/design-system/`, `css/custom.css`, `utils/gtags.client.ts` |
| 38 | +- `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`) |
| 39 | +- `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. |
| 40 | +- `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. |
| 41 | +- `.github/workflows/deploy.yml` — on push to `main`, build check + Typesense scrape using `docsearch.config.json`. `scrape.yml` also exists in the same folder. |
| 42 | + |
| 43 | +## Conventions and Gotchas |
| 44 | + |
| 45 | +- **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. |
| 46 | +- **Docusaurus is pinned to 3.0.0** exactly (no caret). `@docusaurus/core`, `@docusaurus/preset-classic`, and `@docusaurus/module-type-aliases` must move together. |
| 47 | +- **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`). |
| 48 | +- **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. |
| 49 | +- **Code Hike is active on all docs code blocks** (`remarkCodeHike` with Nord theme, `lineNumbers: true`, `showCopyButton: true`). Standard fenced code blocks work as-is. |
| 50 | +- **Sidebar is autogenerated.** Control labels and position via each folder's `_category_.json`, not by editing `sidebars.js`. |
| 51 | +- **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. |
| 52 | +- **URL redirects belong in `vercel.json`**, not page front-matter. Follow existing patterns there when restructuring. |
| 53 | +- **Licensing is split:** source under Apache 2.0 (`LICENSE.txt`), content under CC-BY-4.0 (`CC-BY-4.0.txt`); see `LICENSE.md`. |
| 54 | + |
| 55 | +## Files Not to Modify |
| 56 | + |
| 57 | +- `package-lock.json` — regenerated by `npm i` |
| 58 | +- `/node_modules`, `/build`, `.docusaurus/`, `.cache-loader/` — gitignored build artifacts |
| 59 | +- `static/llms.txt` — curated for LLM discovery; verify source before editing |
0 commit comments