Audit MDX frontmatter quality and SEO metadata

[mintlify]

Summary

Audited all 373 MDX files for SEO, metadata, style, and structural issues. Applied automatic fixes to frontmatter; remaining items require human judgment and are listed below.

Automatic fixes (90 files)

Replaced broken/placeholder descriptions

Three GPv2 contract reference pages had description: "import HistoricalFact from './_gpv2.md'" (a stray import that ended up as a duplicate description). Replaced with concise, contract-specific summaries:

• cow-protocol/reference/contracts/core/allowlist.mdx
• cow-protocol/reference/contracts/core/settlement.mdx
• cow-protocol/reference/contracts/core/vault-relayer.mdx

Rewrote descriptions with orphan link gaps

24 pages had descriptions that were extracted from page bodies during a prior import — markdown link text was stripped leaving telltale double spaces (e.g. "leveraging the to execute…"). Rewrote each as a concise, SEO-friendly summary that mentions CoW Protocol / CoW Swap / CoW DAO. Notable examples:

• cow-protocol/explanation/architecture/solver-engine.mdx
• cow-protocol/explanation/order-types/cow-hooks.mdx
• cow-protocol/reference/contracts/periphery/eth-flow.mdx
• cow-protocol/reference/core/auctions.mdx
• cow-protocol/reference/core/tokens.mdx
• governance/explanation/snapshot.mdx
• governance/reference/multisigs.mdx

Shortened over-length descriptions (>160 chars)

Trimmed 34 descriptions that exceeded the 160-character SEO limit (some up to 575 chars), keeping the technical meaning intact. Affected directories include cow-protocol/explanation/, cow-protocol/reference/, cow-protocol/tutorials/, cow-swap/, composable-cow/, bff/, and governance/.

Lengthened too-short descriptions (<50 chars)

Expanded 12 short or stub descriptions to include CoW Protocol / product context for SEO:

• changelog.mdx, mevblocker.mdx
• cow-py/api/contracts.mdx, cow-py/api/subgraph.mdx, cow-py/installation.mdx
• hooks-trampoline/api/errors.mdx
• watch-tower/advanced/storage.mdx, watch-tower/deployment/dappnode.mdx, watch-tower/deployment/docker.mdx

Added missing descriptions (13 pages)

• cow-amm/explanation/how-cow-amms-work.mdx
• cow-amm/tutorials/cow-amm-for-solvers.mdx
• cow-protocol/explanation/architecture/autopilot.mdx
• cow-protocol/howto/solvers/onboard.mdx
• cow-protocol/howto/solvers/routes_integration.mdx
• cow-protocol/reference/core/definitions.mdx
• cow-protocol/reference/sdks/cow-sdk.mdx
• cow-swap/hooks/hook-dapp.mdx
• governance.mdx, governance/explanation/process.mdx
• governance/reference/cip-template.mdx, governance/reference/fees.mdx, governance/reference/partner-fee.mdx

Added sidebarTitle for long page titles (>30 chars)

Added concise sidebar titles to 17 pages so navigation labels stay readable, including:

• cow-amm.mdx (CoW AMM overview)
• cow-amm/explanation/the-problem-of-lvr.mdx (The problem of LVR)
• cow-protocol/explanation/introduction/fair-combinatorial-auction.mdx (FCBA)
• cow-protocol/howto/solvers/onboard.mdx (Joining the solver competition)
• cow-protocol/reference/core/auctions/the-problem.mdx (The solving problem)
• cow-sdk/guides/erc1271-signing.mdx (ERC-1271 signing)
• cow-swap/tutorials/dca-twap.mdx (DCA with TWAP)

Validation

• mint validate — passed
• mint broken-links — passed

Issues requiring human judgment

The audit also surfaced findings that are out of scope for automatic remediation. Listing them here for follow-up.

Diataxis compliance / mixed concerns

Several pages mix more than one Diataxis quadrant. Suggested splits / re-classifications:

• cow-protocol/howto/integrate/api.mdx — currently a 713-line "guide" that contains tutorial walkthrough, how-to recipes, and reference material. Consider splitting into a tutorial (tutorials/integrate-via-api) plus targeted how-to pages.
• cow-protocol/howto/solvers/onboard.mdx — mixes explanation ("Why join?") with how-to steps. The explanatory sections could move under cow-protocol/explanation/.
• cow-protocol/tutorials/cow-amm-deployer.mdx — described as a "tutorial" but reads like a feature overview. Consider moving to cow-protocol/explanation/ or rewriting around concrete, hands-on steps.
• cow-swap/hooks/hook-dapp.mdx — currently a link hub. Either expand into a real explanation/how-to page or replace with a Cards block on a parent index.

Verbose introductions / leading with filler

Pages where the opening prose buries the answer:

• cow-protocol/howto/cow-explorer.mdx (line 1+) — leads with off-chain/on-chain context before explaining what the explorer does.
• cow-protocol/tutorials/solvers/local_test.mdx (line 1+) — opens with "CoW Protocol infrastructure is a lot of services running together in herd harmony…" before stating the goal.
• cow-swap/tutorials/native.mdx — first paragraph defines "native token" generically rather than telling the reader what they will achieve.
• governance/explanation/token.mdx — opening paragraph is marketing copy; could lead with concrete utility.

Component usage

• ~212 fenced code blocks across the docs are missing language identifiers. High-impact directories: bff/, composable-cow/, cow-protocol/explanation/how-it-works/how-intents-are-formed.mdx, cow-protocol/howto/, cow-sdk/, services/. Many appear to be JSON, JavaScript, or shell snippets — adding json, js, bash, solidity tags would improve syntax highlighting and accessibility. Sample locations:
  • bff/api-reference/endpoints/accounts.mdx:112,118,125
  • composable-cow/tutorials/custom-order-type.mdx:12,36,348
  • cow-protocol/explanation/how-it-works/how-intents-are-formed.mdx:13,21,220,230,244,252,262,274
• Several procedural how-to pages (e.g. cow-protocol/howto/integrate/api.mdx, cow-protocol/howto/solvers/onboard.mdx) use bare ordered lists where <Steps> would render more clearly.
• cow-protocol/explanation/order-types/liquidations.mdx and cow-protocol/howto/cow-explorer.mdx would benefit from <Note>/<Warning> callouts on key caveats currently rendered as plain text.

Other notes

• cow-protocol/reference/contracts/core/{allowlist,settlement,vault-relayer}.mdx reference an import HistoricalFact from './_gpv2.md' line in their bodies — left untouched here because it appears to be intentional content reuse, but worth confirming the import resolves correctly.
• cow-protocol/reference/sdks/cow-sdk.mdx is marked hidden: true and largely contains test-coverage and badge content. Consider deleting or replacing with a proper landing page.
• cow-amm.mdx is marked hidden: true but is the canonical CoW AMM marketing page; verify whether this should be visible.

No technical content was changed — only frontmatter, descriptions, and sidebar titles.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cow-protocol	🟢 Ready	View Preview	May 4, 2026, 9:21 AM