Yearn Protocol Documentation Website

The Yearn Docs website is built using Docusaurus, a modern static website generator.

Installation and Setup

1. Fork the yearn-devdocs repository at https://github.com/yearn/yearn-devdocs

2. clone your forked repo locally. Replace <yourUserName> with your github user name

   git clone https://github.com/<yourUserName>/yearn-devdocs
   cd yearn-devdocs

Install project dependencies

1. Install Node dependencies

   make sure you have the most recent lts node version installed. NVM is Node Version Manager and you may need to install this if you don't have it.

   nvm install --lts

   nvm use --lts
   

Then install dependencies with Bun

bun install

2. Install Python/Vyper dependencies for natspec docs generation (You can skip this step if you aren't working on smart contract documentation)

   This assumes you are using linux and will use the apt package manager. If not, other OSes have their own package manager that will have Python and Vyper. The legacy V2 vyper==0.3.7 dependency in requirements.txt only supports Python >=3.7,<3.11, so use Python 3.10.x for this setup.

   2a. update the apt package manager

   sudo apt update

   2b. Install Python 3.10

   sudo apt install python3.10 python3.10-venv

   If python3.10 is not available from apt on your distro (for example Ubuntu 24.04), install it with a version manager such as uv instead:

   uv python install 3.10

   2c. Verify the installation

   python3.10 --version

   2d. Create and initialize python virtual environment

   python3.10 -m venv venv
   source venv/bin/activate

   If you installed Python 3.10 with uv, create the environment with:

   uv venv --python 3.10 --seed venv
   source venv/bin/activate

   2e. install requirements

   python3 -m pip install -r requirements.txt

   For V3 3.1.x, use the separate environment and compiler requirements described in Generating V3 Smart Contract Documentation.

   2f. Install Foundry

   curl -L https://foundry.paradigm.xyz | bash

   open a new terminal window and run

   foundryup

Local Development

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

bun run start

Running bun run start will also run a script that checks the validity of smart contract addresses in the docs against a local constants file. This runs on every dev run as a way to keep the checks updated and the information about them on the site current (all PRs will include an update to last check time). If you want to start without the runAddressChecks script you can run bun run start-no-check.

Build

This command generates static content into the build directory and can be served using any static content hosting service.

bun run build

AI / agent exports

The build also generates AI-friendly artifacts that will be served by the hosted site:

• build/llms.txt (served as /llms.txt)
• build/ai/manifest.json (served as /ai/manifest.json)
• build/ai/docs.jsonl (served as /ai/docs.jsonl)
• build/ai/raw/ (served as /ai/raw/, with an index page plus raw .md/.mdx files)

Artifact URLs default to https://docs.yearn.fi. To generate artifacts against a preview deployment, set DOCS_URL explicitly (for example DOCS_URL=https://<preview-host>).

Configure .env

The docs site pulls data from on-chain smart contracts and now resolves RPCs by chain. Copy .env.example to .env and set any RPC_URI_FOR_<chainId> values you want to override.

By default, the repo will use Yearn RPC endpoints in the form https://rpc.yearn.fi/chain/<chainId>, so the example values can usually be used as-is.

Runtime docs reads use the chain declared in each page's rpcCalls frontmatter. The address-check script is still mainnet-only today, so it uses chain 1.

The site reads vault snapshots from Kong. Set KONG_ENDPOINT only when you need to point at a different Kong-compatible REST host.

ALCHEMY_API_KEY is no longer read by the site. Use RPC_URI_FOR_1 for mainnet RPC overrides.

Deployment

Generally you should not need to use this as there is a github actions script that builds and deploys the site when a pull request is merged to the master branch of the upstream Yearn GitHub Repo.

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push it to the gh-pages branch.

GIT_USER=<Your GitHub username> USE_SSH=true bun run deploy

---

Contribute

For detailed information on the contributing workflow, please see the Contributing Documentation.

Documentation Structure

We have 2 types of documentation: General documentation and Natspec documentation of smart contracts:

• General documentation is generated from markdown or HTML files and edited manually.
• Natspec documentation is automatically generated from another repository's code.

General Documentation

This documentation is located in the docs folder and most content is either in the getting-started folder (User Docs), the developers folder (Dev Docs), or the contributing folder (DAO Docs).

Natspec Documentation

⚠️ As of mid 2024, versioning has been changed!

Because Yearn supports multiple products with their own version numbers, versioning is now done manually using folder structure (instead of native Docusaurus versioning) to keep things organized. There are folders for all versions of the smart contract NatSpec documentation in:

docs/developers/smart-contracts
├── V3
│   ├── Current contract 1
│   ├── Current contract 2
│   └── Current contract n...
│
├── V2
│   ├── Current contract 1
│   ├── Current contract 2
│   └── Current contract n...
│
├── Deprecated
│   ├── V3 Deprecated
│   │   ├── v3.x.x
│   │   │   ├── contract 1
│   │   │   ├── contract 2
│   │   │   └── contract n...
│   │   └── v3.x.x
│   │       ├── contract 1
│   │       ├── contract 2
│   │       └── contract n...
│   │
│   └── V2 Deprecated
│       ├── v0.4.x
│       │   ├── contract 1
│       │   ├── contract 2
│       │   └── contract n...
│       └── v0.4.x
│           ├── contract 1
│           ├── contract 2
│           └── contract n...

Generating V2 Versioned Documentation

Dependencies

• Clone the V2 vaults repository: yearn/yearn-vaults in the same folder where you cloned yearn-devdocs (not inside devdocs, but beside it)
• Run the yearn-vaults installation, you will need to have brownie installed to run it once so it installs the required dependencies.
• Check the vyper compiler version on the vaults repo (here) and update the vyper version in the requirements.txt file in this repo.
• Make sure Vault.vy and Registry.vy on yearn-vaults folder has the same compiler version on their first line. If not, bump the file with the lowest version to the current version the other uses.
• If any contract file in yearn-vaults uses a fixed compiler version (without leading ^) you may have to add it so the solc compiler will run. Also, make sure solc version is up-to-date.
• If you get errors with global solc try to install it locally on the project with npm

Generate

To generate API documentation and coin a new release, do the following.

1. Create new folder in docs/developers/smart-contracts/deprecated/V2 with the current version number (i.e. version-0.4.6)
2. Move existing docs into newly created folder. Leave the index.md file and update the vault version called out in it to the new version number.
3. Generate docs from contracts using vydoc or similar documentation creator.
4. lint and clean up docs
5. Move new generated docs into docs/developers/smart-contracts/v2/

VyDoc

Generate docs with vydoc. Arguments are: -i is where the smart contracts live -o is where the generated documentation will be written -t is the template used to generate the docs -c is the compiler (make sure you have the correct vyper installed)

bunx vydoc -i ../yearn-vaults/contracts/ -o ./natspec/temp -t ./natspec/contract.ejs -c $(which vyper)

npx solidity-docgen@0.5.17 --solc-module solc --templates=natspec --helpers=helpers/solidityHelpers.js -i ../yearn-vaults/contracts/ -o ./docs/developers/smart-contracts/v2

Generating V3 Smart Contract Documentation

V3 NatSpec is generated locally and committed as Markdown. CI builds the committed pages; it does not fetch contract releases or regenerate NatSpec.

Setup

Install the JavaScript dependencies with bun install and install Foundry (forge). Use a separate Python environment for V3 so the legacy V2 compiler is unchanged:

uv venv --python 3.10 --seed venv-v3
source venv-v3/bin/activate
python -m pip install -r natspec/requirements.txt

Alternatively, use python3.10 -m venv venv-v3 instead of uv venv. V3 releases 3.1.0 and 3.1.1 require Vyper 0.3.10. The root requirements.txt continues to pin Vyper 0.3.7 for legacy V2 generation. If the environment is not activated, set VYPER_BIN to the absolute path of its vyper executable.

The five contract repositories live in natspec/lib as Git submodules. The script initializes them and their dependencies as needed, then checks out the exact commits recorded for the requested release in natspec/releases.json. It never updates from a moving remote branch and refuses to overwrite uncommitted source changes.

Generate a release

bun run v3-docs --version 3.1.1

When the requested version differs from the current version, the script generates and validates a complete replacement first, archives the existing directory under docs/developers/smart-contracts/deprecated/V3/version-<old-version>, then installs the new pages in docs/developers/smart-contracts/V3. Repeating the command for the current version refreshes it without creating another archive. An existing archive is never overwritten by the release rollover.

To generate a missing historical version without changing current docs:

bun run v3-docs --version 3.1.0 --output docs/developers/smart-contracts/deprecated/V3/version-3.1.0

Running bun run v3-docs without arguments retains the interactive new and update options. For update, choose all or selected; selected file names come from filesToUpdate, and selected folders come from folderToUpdate in natspec/scripts/natspec-generate.mjs. Folder selection includes Markdown in subfolders. Contract names must match smartContracts.json (for example, TokenizedStrategy or CommonTrigger).

Sources and validation

Before generating another release, add its compiler version and exact repository commits to natspec/releases.json. For the two core repositories, record the release tag and resolve it to its commit. The script also verifies that both contract sources declare the requested API_VERSION.

Periphery repositories have independent release schedules. The recorded 3.1.x periphery inputs are default-branch snapshots as of each vault release commit's timestamp, not separately tagged 3.1.x releases. Their exact commits appear on the generated index page and in sources.json beside each complete generated set. smartContracts.json controls which contracts are published and their folder layout; its git field determines the owning source repository.

Forge generates Solidity pages. VyDoc uses natspec/contract.ejs and the pinned Vyper compiler for VaultV3.vy and VaultFactory.vy. Unpublished Vyper utilities in the periphery repositories are excluded from the Solidity pass. Every expected contract must have exactly one generated page before any published pages move. The copy step rewrites Forge links and escapes MDX-sensitive prose while preserving code examples. Generation errors exit nonzero and leave the published pages in place.

The 3.0.4 archive preserves the previously published Markdown, including periphery pages updated at different times. It is not a freshly regenerated release set; its index and sources.json describe that provenance. The 3.0.3 archive is retained unchanged.

After generation, review the diff and build the site:

bun run test:natspec
bun run build

---

Custom Elements

Detail Element

This is a Detail element that contains other text inside. If you format the summary section as shown it renders markdown correctly.

<details className="customDetails">

  <summary>

  ## Title Here

  </summary>

### Subtitles as needed

content here

</details>

There is also a "customFaqDetails" css class that removes the borders.

PrettyLink

The PrettyLink element makes your links into button-like elements with subtle animation and yearn styling. These links will fill the full width of the markdown document. Can be used with naked links or with markdown style links.

<PrettyLink>[your link name](your-link-url)</PrettyLink>

Yearn Admonition

There are custom informational Yearn-styled admonitions that can be used like any other admonition.

:::yearn[title-goes-here]

text content

:::

:::yearn-data[title-goes-here]

text content

:::

If you create a new docs plugin in docusaurus.config you will need to initialize this admonition in that plugin instance like this:

 plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'new docs section',
        //other vars
        admonitions: {
          keywords: ['yearn', 'yearn-data'],
          extendDefaults: true,
        },
      },
    ],
]

Blockchain RPC Calls

You can make RPC calls to read contract data from on-chain sources and display them within the docs. This is done using the Viem ethereum library. But if all you are doing is writing docs, you don't need to worry about the details here. You can add the information for all the read calls you want within the front-matter of a markdown document. Front-matter is metadata that docusaurus reads when serving pages.

To make a blockchain call you need to structure your data in the following format:

---
rpcCalls:

  - name: 'dYFI Redemption' <-- descriptive name of contract to be called for use in component
    chain: '1' <--chainID
    address: '0x7dC3A74F0684fc026f9163C6D5c3C99fda2cf60a' <--the contract address
    abiName: 'dyfiRedemptionABI' <--name of exported ABI object from src/ethereum/ABIs
    methods:
      - 'discount' <-- name of call (if no arguments needed)
      - 'get_latest_price'
      - name: 'eth_required' <-- name of call (if arguments are needed)
        args: ['1000000000000000000'] <--comma separated arguments of call as an array (square brackets)

  - name: 'YFI token'
    chain: '1'
    address: '0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e'
    abiName: 'yfiTokenABI'
    methods:
      - totalSupply
      - symbol
---

• Each element in rpcCalls creates an object that is exported from the front-matter.
• Each object can contain calls to different functions in the same contract if you add them into the methods field.
  • If the method doesn't require args (the function doesn't require any input) then you only need to list the name. This is the name you see on etherscan, without the number.
  • If the method does require an argument then you need to add it with a name parameter and an args parameter, with the values for the arguments separated by commas and in square brackets.

⚠️ When adding a new contract to call, you need to add the ABI to "src/ethereum/ABIs". Create a new typescript file with the name of your ABI. The convention is to name it in camelCase and end it with ABI (i.e. yfiTokenABI.ts). Then paste the ABI into the file (you can copy it from etherscan. It is in the contract->code section.). You need to export it and add as const at the end.

// src/ethereum/ABIs/yourContractABI.ts
export const yourContractABI = [
    {
    // abi data here
    }
] as const

You then need to export this element from the index.ts file in the same directory. Add a line exporting your ABI as shown below.

export * from './yourContractABI'

To display the data from the calls, use the <ContractData> component. It takes the following arguments:

• contractName which reads the name field in the rpcCall defined in the front-matter
• methodName which reads from the methods in the rpcCall defined in the front-matter
• decimals which is an optional argument to format your output to display with human readable decimals. It should be wrapped in curly brackets {}.

The current redemption discount is: <ContractData contractName='dYFI Redemption' methodName='discount' decimals={18} />