Chainlink documentation: the MDX source behind docs.chain.link

A documentation site that is also an Astro application

The repository is the source for the developer documentation at docs.chain.link, and the readme describes its audience as smart contract developers and node operators building decentralized applications on several networks. The primary language is MDX, and the build system is Astro, with astro.config.ts at the root and a dev script that runs astro dev.

The interesting part for anyone looking at how a large documentation site is put together is the shape of the pipeline. The build script sets NODE_OPTIONS with a max old space size of 8192 and then delegates to build:pipeline, and that pipeline is a chain of six steps. The same manifest also carries a development command that starts the Astro server locally.

npm install && npm run dev

Read left to right, the pipeline validates the CCIP directory data, syncs the product documentation into the large language model facing artefacts, generates a search index, builds the site, pins the Solidity version, and then cleans up a Vercel function. Each of those steps is a separate script with a name that says what it does, which is a reasonable convention for a repository where the docs are generated as much as they are written.

The repository root shows the rest of the tooling. There is a codegen.ts and a codegen script, a linkmap.json, a lychee.toml for link checking with both internal and external modes in the scripts, a context7.json, a postman/ directory, a templates/ directory, a foundry.toml and a remappings.txt for the Solidity side, a jest config, an eslint config, a solhint config, a prettier config, a .husky/ directory, and a CODEOWNERS file.

The Node requirement is 20 or newer, and the manifest marks the package private with devEngines entries for both the node runtime and the npm package manager, both set to fail on error. That is a stricter setup than most documentation repositories, and it reflects a codebase that runs real codegen rather than just rendering markdown.

Content in markdown, navigation in JSON, search in Algolia

The docs architecture section is three lines long and covers the whole structure.

All docs are markdown and stored in /src/content. Navigation is JSON in /src/config/sidebar.ts. And SEO metadata has its own guide, the SEO Metadata Guide, which is written for technical writers rather than for engineers.

That third item is the one that tells you the most about the project. A dedicated guide for authors on how to produce SEO metadata means the site treats discoverability as a first class authoring concern, not something a build script handles behind the scenes. For a documentation site with thousands of pages across dozens of products and networks, having a written convention for titles and descriptions is what keeps the pages from becoming indistinguishable in search results.

Search is Algolia, and the environment file shows the shape of it. The .env.example file carries an Algolia app id, a write API key, an index name of docs-test, and separate public application id and public search key variables, plus a CCIP GraphQL endpoint and API key. The separation between the write key and the public search key is the standard Algolia arrangement, and the index name in the example being docs-test suggests a staging index for local work.

The rest of the root is a set of small quality tools. A markdown linter configuration for the prose, a solhint configuration and ignore file for the Solidity samples, a .prettierignore and .prettierrc, an eslint config and ignore file, a knip.json for finding unused code, a .tool-versions file and an .nvmrc for pinning tool versions, and a middleware.ts at the root, which is the Astro middleware for the site.

So this is a documentation site with a full linting and type discipline, which is unusual and is the main reason to read the repository rather than only the published pages.

Version pinning for sample files, and why a tutorial needs it

The version-overrides mechanism is the most transferable idea in the repository, and it solves a problem that anyone who has written a tutorial with a code sample eventually hits.

The problem is that the Chainlink contracts packages move, and a sample that worked against one version of @chainlink/contracts will break against the next. If the site pins one version globally, then a tutorial that needs a specific older version cannot be shown accurately. If it pins nothing, every sample is written against whatever is current and stops working the moment a release lands.

The solution here is a per-file override file, version-overrides.json, with an array of override objects.

{
  "overrides": [
    {
      "file": "samples/CCIP/example.sol",
      "reason": "Tutorial requires specific version",
      "versions": {
        "@chainlink/contracts": "1.5.0"
      }
    }
  ]
}

Each entry names the sample file it applies to, gives a reason that a human reads, and lists the package versions to use for it. The build step is a separate script, pin-sol-version, which the readme says has its TypeScript types in src/scripts/helper/pin-solver-dist.ts, so the shape of the structure is discoverable from the type definitions.

The reason field is the detail worth copying. An override without a reason is a mystery six months later, when someone wants to know whether the pin is still needed. With a reason, a reviewer can tell at a glance whether the override is still justified.

There is a second, related tool in the same area. The pin-sol-version script is paired with a cleanup step for a Vercel function at the end of the pipeline, which suggests the Solidity pinning is partly there to support a server side function that resolves versions at request time rather than baking them in at build time. The readme does not explain that in detail, so anyone extending this should look at the scripts directory rather than assume.

Preview environments on every pull request

The deployment model is described in two short paragraphs and it is the part that most affects how a contributor works.

This repo is configured to automatically create a preview environment on Vercel when a pull request is opened. After the deployment is approved, the Vercel bot leaves a comment with a link to the preview on the pull request. And the repo is configured to automatically update the production site at docs.chain.link when commits are pushed to the main branch.

The approval step is worth noticing. Automatic preview creation is common, but automatic approval is not, and having a human approve means the preview environment is available for review before anyone looks at it. The result is that a documentation pull request can be judged as a website rather than as a diff of markdown, which for a site with interactive examples and generated search is the only practical way to review it.

The production path is fully automatic from main. That is a deliberate trade. A documentation site that publishes on merge gives fast turnaround, and it depends on the CI checks being good enough to catch broken content before it ships. The repository's link checking setup, with separate internal and external link check scripts and a lychee configuration, is part of that safety net, as is the CCIP data validation step that runs first in the pipeline.

The link checking is worth a second look. There are two scripts, linkcheck-internal and linkcheck-external, with the external one passing a mode flag. A documentation site links out to API references, block explorers and other services, and those links rot. Checking them separately from internal links makes sense, since an external failure is often a service being down rather than a mistake in the page, and you do not want to block a pull request because someone else's site is having an incident.

The repository also has a script.sh at the root and a scripts/ directory, and a bin/ directory, which are where the remaining task runners live.

The disclaimer is longer than most feature descriptions

The readme carries two disclaimers, and the second one is a very long paragraph, which tells you something about how the project handles responsibility for its examples.

The first is a callout note. The code samples in the documentation are examples for using Chainlink products and services, provided to help you understand how to interact with Chainlink's systems so that you can integrate them into your own. They are provided as is and as available without warranties of any kind, they have not been audited, and they may be missing key checks or error handling. The note says not to use the example code in a production environment without completing your own audits and application of best practices, and that neither Chainlink Labs, the Chainlink Foundation nor Chainlink node operators are responsible for unintended outputs generated due to errors in the code.

The second disclaimer, at the end of the readme, goes considerably further. It says the repo contains community examples only, that these are not Chainlink products or services and are not supported or maintained by Chainlink, and that the code is intended for demonstration and educational purposes only. Each party intending to use the example code does so entirely at their own risk and must perform its own audits, security and code review, key management and testing before any production deployment. It states that neither Chainlink Labs nor the Chainlink Foundation deploys, operates, monitors, maintains or endorss any deployment of that code, that this is not a Chainlink product, feature or service, and that there are no commitments made with respect to the code, including compatibility with future Chainlink releases. It states that the code is outside the scope of any Chainlink bug bounty programmes, and that use of the Chainlink Network is subject to the Chainlink Foundation Terms of Service.

For a project whose entire value is that people copy code out of it, that is the correct framing and it is unusually thorough. The key sentence for an adopter is the one about compatibility with future Chainlink releases. A sample pinned to a specific version of the contracts package is not guaranteed to keep working, which is exactly what the version-overrides mechanism exists to manage, and exactly why a tutorial written today may need adjusting in six months.

The licence field on the repository is listed as a custom one that GitHub cannot classify, and there is a LICENSE file in the root. That matters more than usual here, because the content in this repository is a large body of code samples that people copy into their own projects, and what you may do with that code depends on the terms of that file rather than on the terms of the services being documented. Read it before redistributing a sample.

Where the Chainlink docs are the wrong source

There are three cases where reading this repository is the wrong move, and one where it is the only move.

The first wrong case is looking for the Chainlink contracts themselves. This repository documents how to use Chainlink services; it is not where the contracts live, and the samples in it are demonstration code rather than the audited, versioned artefacts a production deployment should use.

The second is looking for a production hardened example. The readme says twice that the samples have not been audited and may be missing key checks or error handling. A sample meant to make a concept clear is not a sample with a complete validation layer, and if you deploy one without writing the checks yourself, you have deployed something the project explicitly warned against.

The third is a legal or compliance question. This is documentation, and the disclaimer points at the Chainlink Foundation Terms of Service for the terms that actually govern use of the network. Nothing in this repository answers questions about obligations, and a technical writer reading it will not find them.

The case where it is the right source is a narrow one and it is genuinely useful: understanding exactly which parameters a call expects, in what order, and what the failure modes look like, for a service version you are about to use. The docs are the reference for the call surface, and the version overrides and per-file pinning mean that a page telling you which package version its sample needs is telling you something specific rather than approximately.

On the alternative, the difference in approach against a code-first source is where the authority sits. A code-first route, reading the contract source or the type definitions in the package you have installed, tells you exactly what the current release does, including the edge cases the documentation has not caught up with. The documentation tells you how the maintainers intend the service to be used and what the recommended pattern is, and it moves at the pace of the docs team rather than the pace of the release. For a released version, the code is more accurate. For a recommended pattern, the documentation is the only source. The version-overrides file is the bridge between the two, since it tells you which version of the code a given page was written against.

Editorial conclusion

This repository suits a smart contract developer who needs to check how a Chainlink service is meant to be called, and a technical writer who wants to contribute a tutorial, and it does not suit someone who wants a copy of the Chainlink contracts themselves or a production hardened sample. Before you copy anything from it, read the disclaimer, which states the samples are provided as is, have not been audited, may omit checks and error handling, and sit outside the scope of any Chainlink bug bounty programme, and note that the licence on the repository is a custom one that GitHub cannot classify.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. smartcontractkit/documentation on GitHub