docs: audit metadata, SEO descriptions, and sidebar titles

[mintlify]

Summary

Audited all 373 MDX pages for SEO, metadata, style, and structural issues. This PR fixes everything that could be resolved automatically without touching technical content; items that need human judgment are listed at the bottom.

Automatic fixes applied (63 files)

Broken descriptions

Three pages had description: "import HistoricalFact from './_gpv2.md'" (a leftover import statement, not a real description). Rewrote with proper SEO descriptions and added sidebarTitle:

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

Several other descriptions had broken link artifacts (e.g. "A simple (TWAP) trade may be thought of as smaller trades...", "leveraging the to execute...") — left over from removed markdown links. Rewrote these to coherent SEO descriptions on:

• cow-amm/explanation/the-problem-of-lvr.mdx
• cow-protocol/explanation/architecture/solver-engine.mdx
• cow-protocol/explanation/benefits/trade-any-intent.mdx
• cow-protocol/explanation/how-it-works/flow-of-an-order.mdx
• cow-protocol/explanation/introduction/intents.mdx
• cow-protocol/explanation/order-types/cow-hooks.mdx
• cow-protocol/explanation/order-types/programmatic-orders.mdx
• cow-protocol/reference/contracts/periphery/composable-cow.mdx
• cow-protocol/reference/contracts/programmatic/twap.mdx
• cow-protocol/reference/core/auctions.mdx
• cow-protocol/reference/core/auctions/ebbo-rules.mdx
• cow-protocol/reference/core/auctions/rewards.mdx
• cow-protocol/reference/core/intents/hooks.mdx
• cow-protocol/reference/core/signing-schemes.mdx
• cow-protocol/reference/core/tokens.mdx
• cow-protocol/tutorials/cow-amm-deployer.mdx
• cow-protocol/tutorials/cow-explorer/address.mdx
• cow-protocol/tutorials/cow-explorer/batch-auction.mdx
• cow-protocol/tutorials/cow-explorer/order.mdx
• cow-swap/widget/params.mdx
• cow-protocol/explanation/flash-loans/integrators.mdx
• cow-protocol/explanation/order-types/pay-debt-flash-loans.mdx

Added missing description (12 pages)

All pages without a description (excluding snippets/*, which are partials) now have a 50–160 character SEO-friendly description mentioning CoW Protocol/CoW Swap/CoW AMM where relevant:

• 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

Expanded too-short descriptions (<50 chars)

• 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

Trimmed overly long descriptions

Brought several descriptions above 200 characters back into the 130–160 SEO sweet spot, including: cow-amm.mdx, cow-protocol/explanation/architecture/driver.mdx, cow-protocol/howto/cow-explorer.mdx, cow-protocol/reference/core/auctions/accounting.mdx, governance/explanation/mission.mdx, governance/explanation/token.mdx.

Added sidebarTitle to long titles (>30 chars)

All 17 pages with titles over 30 characters now have a concise sidebarTitle, including BFF services, CoW AMM, the CoW Hook deployer, FCBA, solver tutorials, ERC-1271 signing, DCA TWAP, and the GPv2 contract reference pages.

Validation

• mint validate ✅
• mint broken-links ✅ (no broken internal links)

Items requiring human judgment (not changed)

Slightly long descriptions (161–202 chars)

The following pages have descriptions slightly above Google's 160-char cap. They read well and use no broken markup, so I left them alone — please review and trim if you want strict SEO compliance:

• bff/services/api.mdx (172)
• composable-cow/introduction.mdx (168)
• cow-protocol/explanation/fee-model.mdx (202)
• cow-protocol/explanation/how-it-works/coincidence-of-wants.mdx (166)
• cow-protocol/explanation/how-it-works/how-intents-are-formed.mdx (193)
• cow-protocol/explanation/order-types/liquidations.mdx (190)
• cow-protocol/explanation/order-types/twap-orders.mdx (226)
• cow-protocol/howto/integrate/api.mdx (161)
• cow-protocol/howto/integrate/sdk.mdx (184)
• cow-protocol/overview.mdx (173)
• cow-protocol/reference/core/auctions/competition-rules.mdx (166)
• cow-swap/features.mdx (167)
• cow-swap/reference/custom-links.mdx (209)
• cow-swap/tutorials/native.mdx (242)
• cow-swap/tutorials/twap.mdx (190)
• cow-swap/widget/overview.mdx (210)
• governance/explanation/grants/grant-types.mdx (194)

Code blocks without language identifiers (~220 occurrences)

A bulk grep found roughly 220 fenced code blocks across the docs that have no language tag. They span Solidity, JSON, TypeScript, plain output, and URLs, and require human review to tag correctly. The highest-density files are:

• cow-protocol/reference/contracts/core/*.mdx (Solidity)
• cow-protocol/reference/contracts/periphery/composable-cow.mdx (Solidity, 16 blocks)
• cow-protocol/reference/contracts/periphery/eth-flow.mdx (Solidity)
• cow-protocol/reference/contracts/periphery/flashloans.mdx (Solidity)
• cow-protocol/howto/integrate/api.mdx (mix of JSON / shell / TS)
• cow-protocol/explanation/how-it-works/how-intents-are-formed.mdx (JSON / TS)
• bff/api-reference/*.mdx (URLs, JSON)
• composable-cow/api/*.mdx and composable-cow/order-types/*.mdx (Solidity)

Recommended fixes:

• Tag URL-only blocks (https://...) as text.
• Tag Solidity signatures (function, event, mapping, address public ...) as solidity.
• Tag JSON payloads / responses as json.

Diataxis & writing style

Most pages follow the diataxis quadrants correctly via the explanation/, howto/, reference/, tutorials/ folders. A few pages mix concerns and could be split or relocated:

• cow-protocol/howto/cow-explorer.mdx mixes explanation with how-to; consider moving the conceptual intro into explanation/.
• cow-protocol/tutorials/solvers/local_test.mdx opens with an explanatory disclaimer ("CoW Protocol infrastructure is a lot of services running together…") that should be replaced with prerequisites and the first step.
• governance/explanation/token.mdx reads more like marketing copy than an explanation; lead with the answer ("COW is the governance token of CoW DAO — used to vote on CIPs and align stakeholders.").

Snippets without frontmatter (expected, no fix)

snippets/*.mdx files are partials imported into other pages, so the absence of title / description is correct.

[mintlify]

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

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