diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..13c3f3b6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# AGENTS.md + +Source of the API3 documentation at https://docs.api3.org, built with VitePress. Content is Markdown under `docs/`, one directory per section, each with its own `sidebar.js`. Sections are registered in `docs/.vitepress/config.js`. [CONTRIBUTING.md](./CONTRIBUTING.md) is the full contributor guide. + +## Commands + +```sh +pnpm install +pnpm docs:dev +pnpm format +pnpm lint +pnpm docs:build +``` + +`pnpm format` formats the whole project with Prettier. Never hand-format. `pnpm docs:build` regenerates `docs/public/llms.txt` and `llms-full.txt` before building. + +Link validation, the same check CI runs: + +```sh +pnpm docs:build +pnpm docs:serve & +node ./libs/link-validator.js http://localhost:8082 ./docs/.vitepress/dist/ +``` + +## Content rules + +- Every page listed in a sidebar declares `title` and `pageHeader` in its frontmatter and starts its body with ``. A missing `` fails the build. +- A new page goes into the section's `sidebar.js`. A new section needs its own directory with a `sidebar.js` and entries in `config.js` under both `sidebar` and `nav`. +- Images live next to the page that uses them. Anything linked by URL from prose goes in `docs/public`. +- `docs/public/llms.txt` and `llms-full.txt` are generated and gitignored. Never edit them. +- Verify numbers, addresses and quoted CLI output against their source, such as the `api3dao/contracts` repository, on-chain state or API3 Market, before changing them. + +## Writing rules + +- Write API3 in capitals. Lowercase `api3` only in identifiers: package names, paths, URLs and the logo wordmark. Contract names such as `Api3ReaderProxyV1` and deployed product names such as the `Api3 Core` vault keep their own spelling. +- `dAPI` and `dApp` in prose, `dapi` and `dapp` in code identifiers. +- Hyphens instead of long dashes. No semicolons in prose. +- Name the acting entity, such as API3 or the Market frontend, rather than writing "we" in new text. +- Do not write facts that the next change turns false: exact counts of things that grow, closed-world claims about a set, or lists that need an edit whenever an entry appears. Link to the source instead. + +## Pull requests + +- Target `main` and reference the issue in the description, for example `Closes #1`. +- CI runs `pnpm lint`, `pnpm docs:build` and the link validator. Every pull request gets a Firebase preview deployment. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a916b9d7..5ce491f3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,29 +1,46 @@ -# Contributors' guide +# Contributing -Welcome to the API3 documentation repository. This guide will help you get -started with contributing to the API3 documentation. The docs use [VitePress](https://vitepress.dev/), a Vue-powered static -site generator. Follow the steps below to get started. +The docs are a [VitePress](https://vitepress.dev/) site. Content is Markdown under [`docs/`](./docs), one directory per top-level section, and each section owns the `sidebar.js` that defines its navigation. Sections are registered in [`docs/.vitepress/config.js`](./docs/.vitepress/config.js), which the `llms.txt` generator reads too. The landing page is [`docs/index.md`](./docs/index.md). -## Submitting an issue +## Local setup -You can submit an issue if you find any bugs or have any feature requests. -Please make sure to check if the issue already exists before submitting a new -one. +```sh +pnpm install +pnpm docs:dev +``` -## Making a pull request +`pnpm docs:build` writes the production build to `docs/.vitepress/dist` and `pnpm docs:serve` serves that build locally. -After making changes in a feature branch, submit a pull request (PR) against the `main` branch. -Make sure to link the corresponding GitHub Issue in the PR description e.g. -`Closes #1`. You will be able to see the changes within a Firebase preview -deployment that is unique to the PR. The PR will be reviewed by the team and -merged into the `main` branch, which will result in the changes going live into -production. +Both `docs:dev` and `docs:build` first run [`scripts/generate-llms-files.js`](./scripts/generate-llms-files.js), which writes `llms.txt` and `llms-full.txt` into `docs/public` from the section sidebars. Both files are gitignored. Do not edit them by hand. -### Getting started +## Writing a page -After cloning the repo locally, install the dependencies and run the docs locally. +- Start the frontmatter with `title` and `pageHeader`, and the body with ``. The generator reads the frontmatter for the page headings and fails the build when `` is missing. +- Add the page to the section's `sidebar.js`. A new section needs its own directory with a `sidebar.js`, plus an entry in `config.js` under both `sidebar` and `nav`. +- Put images next to the page that uses them. Anything linked by URL from prose goes in `docs/public`, so its path stays stable across builds. +- Write API3 in capitals. Lowercase `api3` is only for identifiers such as package names, paths and URLs, and for the logo wordmark. Contract names such as `Api3ReaderProxyV1` and deployed product names such as the `Api3 Core` vault keep their own spelling. +- Use `dAPI` and `dApp` in prose, `dapi` and `dapp` in code identifiers. +- Use hyphens rather than long dashes, and avoid semicolons in prose. +- Keep pages high level and link to the authoritative source, such as a repository, a contract or API3 Market, instead of duplicating detail that goes stale. -```bash -pnpm install -pnpm docs:dev +## Checks + +Prettier is the only formatter. `pnpm format` formats the whole project and `pnpm format:check` verifies it. The husky pre-push hook runs the check. + +VitePress dead link detection is disabled in the config on purpose. CI builds the site, serves it and checks every internal and external link, including anchors, with [`libs/link-validator.js`](./libs/link-validator.js). Reproduce it locally with: + +```sh +pnpm docs:build +pnpm docs:serve & +node ./libs/link-validator.js http://localhost:8082 ./docs/.vitepress/dist/ ``` + +Hosts that block automated requests are listed in [`libs/link-validator-ignore.json`](./libs/link-validator-ignore.json). + +## Issues and pull requests + +Check the existing issues before opening a new one. Open pull requests against `main` and reference the issue in the description, for example `Closes #1`. CI runs the format check, the build and the link validator on every pull request, and the preview workflow posts a link to a Firebase preview of the site. Merging to `main` deploys the live site. + +## Deployment + +The site is hosted on Firebase Hosting under the project named in [`.firebaserc`](./.firebaserc). The [live workflow](./.github/workflows/firebase-live.yml) deploys every push to `main`, and the [preview workflow](./.github/workflows/firebase-preview.yml) deploys an expiring preview channel for every pull request. diff --git a/README.md b/README.md index b5bf8f95..1aa025ac 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,32 @@ -# API3 documentation - -> Source of the API3 documentation published at https://docs.api3.org - -The site is built with [VitePress](https://vitepress.dev/). Content lives under [`docs/`](./docs), one directory per top-level section. Each section owns its `sidebar.js` and is registered in [`docs/.vitepress/config.js`](./docs/.vitepress/config.js), which the llms generator reads too. The landing page is [`docs/index.md`](./docs/index.md). - -## Development +

+ + + API3 documentation + +

-```sh -pnpm install -pnpm docs:dev -``` - -`pnpm docs:build` produces the production build in `docs/.vitepress/dist` and `pnpm docs:serve` serves it locally. +# API3 documentation -Prettier is the only formatter. Run `pnpm format` to format the whole project and `pnpm format:check` to verify. The husky pre-push hook runs the check, and CI runs it again on every pull request. +> Source of the API3 documentation published at [docs.api3.org](https://docs.api3.org). -## Generated files +## Contents -`docs:dev` and `docs:build` first run [`scripts/generate-llms-files.js`](./scripts/generate-llms-files.js), which writes `llms.txt` and `llms-full.txt` into `docs/public` from the section sidebars. Both files are gitignored. The generator reads the `title` and `pageHeader` frontmatter of every page listed in a sidebar and requires the page body to start with ``, failing the build otherwise. +New to API3 data feeds? Start with the [Quickstart](https://docs.api3.org/dapps/quickstart/). -## Link validation +- **[dApps](https://docs.api3.org/dapps/)**: activating a data feed on [API3 Market](https://market.api3.org), reading it from a contract through `Api3ReaderProxyV1`, integration and security considerations, and how OEV Rewards pay dApps for using the feeds. +- **[OEV](https://docs.api3.org/oev/)**: what Oracle Extractable Value is, how API3 data feeds and OEV feeds work at the contract level, and how searchers use the public Signed APIs. +- **[Curation](https://docs.api3.org/curation/)**: the Morpho vaults API3 curates, their roles and operations, risk management and disclosure. -VitePress dead link detection is disabled in the config on purpose. CI instead builds the site, serves it and checks every internal and external link, including anchors, with [`libs/link-validator.js`](./libs/link-validator.js). Reproduce it locally with: +## AI assistants -```sh -pnpm docs:build -pnpm docs:serve & -node ./libs/link-validator.js http://localhost:8082 ./docs/.vitepress/dist/ -``` +The site publishes an [`llms.txt`](https://docs.api3.org/llms.txt) index and an [`llms-full.txt`](https://docs.api3.org/llms-full.txt) file with the full content of every page, following the [llms.txt convention](https://llmstxt.org/). Paste one of them into a chat, or reference it from your project's agent instructions such as `AGENTS.md`, `CLAUDE.md` or `.cursor/rules`, to give an assistant current context on API3. -Hosts that block automated requests are listed in [`libs/link-validator-ignore.json`](./libs/link-validator-ignore.json). +Coding agents working on this repository read [AGENTS.md](./AGENTS.md). -## Deployment +## Contributing -The site is hosted on Firebase Hosting under the project named in [`.firebaserc`](./.firebaserc). The [live workflow](./.github/workflows/firebase-live.yml) deploys every push to `main`, and the [preview workflow](./.github/workflows/firebase-preview.yml) deploys an expiring preview channel for every pull request. +Issues and pull requests are welcome. [CONTRIBUTING.md](./CONTRIBUTING.md) covers the local setup, page conventions, checks and the deployment flow. Questions go to the [API3 Discord](https://discord.gg/api3dao). -## Contributing +## License -Head to [CONTRIBUTING.md](./CONTRIBUTING.md) for the issue and pull request workflow. +[MIT](./LICENSE). The documentation content is subject to the [API3 terms and conditions](https://api3.org/terms-and-conditions/).