> ## Documentation Index > Fetch the complete documentation index at: https://docs.optimism.io/llms.txt > Use this file to discover all available pages before exploring further. # Content guide > What content belongs on docs.optimism.io, the canonical home for each content type, and how to mark third-party content. This page defines what content belongs on docs.optimism.io and, for every content type, which source is canonical. It exists so that "where does this live?" is settled by citing a rule, not re-argued in every pull request. Reviewers should link the relevant section of this page when requesting changes. The approach is adapted from the Kubernetes [content guide](https://kubernetes.io/docs/contribute/style/content-guide/), which governs kubernetes.io with the same two ideas: a short allowlist test for what the site hosts, and a strict preference for linking canonical sources over restating them. ## What's allowed: the three-clause test Content belongs on docs.optimism.io only if at least one of the following is true (adapted from the Kubernetes content guide's third-party content rules): 1. **It documents first-party OP Stack software** — software whose source of truth lives in [Optimism](https://github.com/ethereum-optimism) repositories, such as the components listed on the [Releases](/releases) page. 2. **It documents third-party software that the OP Stack needs to function** — for example, an L1 execution client or key-management tooling that an OP Stack chain cannot run without. Such content must be marked with the [`` component](#marking-third-party-content). 3. **It routes to canonical content that lives elsewhere** — a selection, orientation, or hub page whose job is to send readers to the right canonical home (for example, a curated matrix of SDKs that links each SDK's own documentation). Content that satisfies none of the three clauses — tooling promotion, project-specific marketing, or documentation for software that is neither first-party nor required by the OP Stack — belongs on the third party's own site, not here. ## Link, don't restate: the dual-sourcing ban Wherever a canonical source already exists, **link it — never restate it**. The Kubernetes content guide states the reason plainly: dual-sourced content "requires double the effort to maintain and grows stale more quickly." In practice: * **Never paraphrase normative protocol text.** Explain the concept in your own words at explanation depth, then deep-link the exact section of the [OP Stack specifications](https://specs.optimism.io/) for the normative definition. * **Never copy reference material from another living document.** If a component's book, README, or upstream API reference already documents something, link to it. * **Never fork a table of facts** (versions, addresses, activation times, flag lists) that another system maintains. Render from the source of truth or link it. ## Canonical homes One home per thing. The matrix below assigns a canonical home to each content type across the three layers of the OP Stack documentation surface — the protocol, the components, and the periphery — and states what docs.optimism.io holds for each. | Layer | Content type | Canonical home | What docs.optimism.io holds | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Protocol | Normative protocol behavior | [specs.optimism.io](https://specs.optimism.io/) | Explanation and routing pages that cite the spec with deep links — never restated normative text | | Protocol | Hardfork activations and chain metadata | [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) | Pages rendered from the registry's structured data, joined — not hand-copied | | Components | Concepts, how-tos, and tutorials for running components | docs.optimism.io (full ownership) | The pages themselves, e.g. the [batcher guide](/chain-operators/guides/configuration/batcher) | | Components | Flags and configuration reference | The component's source at a tagged release | A reference page generated from source where a generator exists; otherwise a hand-maintained page pinned to a named release, e.g. the [batcher configuration reference](/chain-operators/reference/batcher-configuration) | | Components | Implementation internals and developer books (e.g. [kona](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona), [op-reth](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-reth)) | The component's developer documentation, maintained beside its source | Orientation and selection pages that link into the deep material | | Periphery | SDKs and ecosystem tooling (e.g. [viem](https://viem.sh/op-stack), wagmi) | The upstream project's own documentation | One curated hub with a support matrix; every listing marked with `` | Precedents for the matrix, clause by clause: * **Spec joined, never mirrored.** Kubernetes documents feature lifecycles through its structured [feature gates reference](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) rather than copying design documents into prose. * **One identity page per component.** ZKsync documents each service of its stack in a single canonical place ([ZK Stack components](https://docs.zksync.io/zk-stack/components)); Cloudflare publishes a uniform per-product [content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/) so every product's documentation set has the same shape. * **A curated matrix over the periphery.** Stripe's [SDK page](https://docs.stripe.com/sdks) differentiates its client surfaces in one table; ethereum.org publishes written [listing criteria](https://ethereum.org/en/contributing/adding-products/) so curation is policy application rather than per-PR debate. * **The component declares its docs home.** Each component's README should point at its canonical documentation, following the [op-deployer README](https://github.com/ethereum-optimism/optimism/blob/develop/op-deployer/README.md) model. When two pages could both claim a topic, the matrix decides. If the matrix does not cover the case, raise it in the docs PR and propose a new row — amendments to this page go through the same review as any other docs change. ## Marking third-party content This section documents the `` component, following the Kubernetes [`thirdparty-content` shortcode](https://kubernetes.io/docs/contribute/style/content-guide/) pattern: every third-party mention is stamped the same way, so third-party content stays greppable and auditable. Pages or sections that document or list third-party software (clauses 2 and 3 of the [three-clause test](#whats-allowed-the-three-clause-test)) must open with the `` component: ```mdx theme={null} import ThirdPartyContent from "/snippets/third-party-content.mdx" ``` Which renders: Items on this page refer to third-party projects or products that are not maintained by Optimism. They are provided for convenience; refer to each project's own documentation as the source of truth. When an entire page is about a single third-party project or product, use the single-project variant instead: ```mdx theme={null} import ThirdPartyContentSingle from "/snippets/third-party-content-single.mdx" ``` Which renders: This page refers to a third-party project or product that is not maintained by Optimism. It is provided for convenience; refer to the project's own documentation as the source of truth. ## Next steps * Read the [style guide](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/STYLE_GUIDE.md) for voice, tone, and formatting conventions. * Read the [contributing guide](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/DOCS_CONTRIBUTING.md) for development setup and the pull request process. * Have questions? Open an issue in the [Optimism monorepo](https://github.com/ethereum-optimism/optimism/issues).