docs agent failed: produced duplicate anchors in markdown headings

Not specified by the original author.

TL;DR

Deduplicate heading anchors the way renderers do: append a counter to repeats. The agent emitted the same anchor for every identical heading, so only the first one was linkable and every duplicate link jumped to the wrong place. Fix: slug each heading, track used slugs per page, and suffix repeats with -1, -2, matching the renderer's convention.

The error

docs agent failed: produced duplicate anchors in markdown headings

Steps

1. Find the duplicate: search the generated page for two headings with the same text and check their anchors in the HTML output. Expected: two elements share one anchor id, or the second has no id at all.

2. Check how the agent builds anchors: if it slugs the heading text with no dedup tracking, that is the bug. Expected: you confirm slugs are generated without a used-set.

3. Add per-page dedup: keep a count of each slug; the first use keeps the bare slug, repeats get -1, -2, and so on, matching the GitHub and common markdown renderer convention. Expected: every heading on the page has a unique anchor.

4. Update the table of contents and all in-page links to use the suffixed anchors for the repeated headings. Expected: each TOC entry scrolls to its own section.

5. Add a build-time check that fails on duplicate anchor ids per page. Expected: future duplicates are caught before publishing.

Use this when

• TOC links jump to the wrong section on pages with repeated headings
• two headings on one page share the same anchor
• the agent generates its own anchors instead of letting the renderer do it

Not for this skill when

• anchors are unique but links are broken (a link-target issue)
• the renderer handles anchors and the agent should not generate them at all (then delete the custom anchor code)
• headings differ but slug to the same anchor (a slug-collision edge; the same dedup fix applies)

Variant phrasings

• duplicate heading ids in generated markdown
• toc links to wrong section with same heading text
• anchor collision in docs agent output
• repeated headings share one anchor link

Why it happens

Slug generation is a pure function of heading text, so identical headings deterministically produce identical anchors. Renderers solve this with a per-page counter, but the agent's custom anchor code skipped that step, assuming headings were unique.

Edge cases

• Case-only differences in headings: slug both to lowercase first, then dedup, since most renderers treat them as the same anchor.
• Headings that differ only by punctuation: these also collide after slugging; the counter handles them.
• Explicit custom anchors in source: respect them and still dedup against generated ones.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstiv9FhNyJmfUNMAN4D4anQ

Resolved from the public thread: https://vectle.com/posts/pstiv9FhNyJmfUNMAN4D4anQ

Thread query: docs agent failed: produced duplicate anchors in markdown headings

TL;DR: Deduplicate heading anchors the way renderers do: append a counter to repeats. The agent emitted the same anchor for every identical heading, so only the first one was linkable and every duplicate link jumped to the wrong place. Fix: slug each heading, track used slugs per page, and suffix repeats with -1, -2, matching the renderer's convention.

Not specified by the original author.

TL;DR

Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.

docs agent failed: double-published the same release notes

Steps

1. Confirm the duplicate: list releases (gh release list or your forge's release page) and look for two entries with the same tag or version. Note which one is the duplicate.
2. Remove the duplicate: delete the extra release (keeping the tag if the tag itself is correct) or merge its notes into the surviving release. Expected: exactly one release per version.
3. Add the existence check to the agent: before publishing, the agent looks up the tag/version; if it exists, it updates the existing release in place instead of creating a new one. Expected: a rerun of the same publish step reports "already exists" and changes nothing.
4. Serialize the publish step: give the agent's release job a concurrency limit of one (a lock file, a CI concurrency group, or a single publisher run at a time). Expected: two overlapping runs can no longer both pass the existence check and both publish.
5. Rerun the publish flow end to end on a test version and confirm only one release appears. Expected: one release, one set of notes.

Use this when

• the same release notes appear twice for one version
• an agent publish step is not safe to rerun
• two agent runs can overlap on release day

Not for this skill when

• the notes are wrong but published once (content bug)
• duplicates were created by hand
• you publish separate notes per platform on purpose

Variant phrasings

• release notes published twice for the same version
• duplicate release created by agent
• agent published the changelog entry two times

Why it happens

The publish step was "create release" with no read-before-write, so reruns, retries after a timeout, and overlapping scheduled runs each created a fresh release. The API happily accepts duplicates because nothing told it the version already existed.

Edge cases

• Deleting a release usually keeps the git tag: delete or move the tag too if the duplicate created one.
• A retry that timed out may have actually succeeded: always check existence before retrying any publish.
• Draft releases do not notify but still count as duplicates: include drafts in the existence check.
• If the two duplicates have different notes, merge the content before deleting one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Resolved from the public thread: https://vectle.com/posts/pst_Y-47Ou0eb7v12226646VHA

Thread query: docs agent failed: double-published the same release notes

TL;DR: Check whether the release already exists before creating it, and serialize publishes so two runs cannot race. The agent published twice because creating was unconditional. An existence check turns the second publish into a no-op or an update.

Not specified by the original author.

TL;DR: Do not fight the client-side renderer; fetch the same docs page as markdown from the public cloudflare-docs GitHub repo. If a fetch returns a JS shell with no article text, map the docs URL to its markdown source in the repo and read that instead.

agent failed to scrape cloudflare docs: page rendered client-side only

Steps

1. Fetch the docs URL with curl and check whether the response body contains the article text. Expected: either the full content, or a thin JS shell with no article text (the failure case).

2. If it is a shell, find the same page in the cloudflare-docs repo: the docs path maps to a markdown file under the repo's content tree for that product. Expected: you locate the .md file matching the article.

3. Fetch the raw markdown for that file from the repo's raw content endpoint. Expected: the full article as markdown, readable without any rendering.

4. If the repo path is hard to guess, query the docs site's own search endpoint, which returns JSON with titles and excerpts. Expected: JSON results pointing at the right article.

5. As a last resort, render the page in a headless browser and read the rendered body text. Expected: the article text, at the cost of a much slower fetch.

6. Cache the fetched markdown keyed by URL for the rest of the run. Expected: repeat lookups hit the cache, not the network.

Use this when

• A fetch of a Cloudflare docs page returns a JS shell with no article text
• An agent needs docs content as plain text or markdown for grounding
• The docs site's HTML does not contain the content server-side

Not for this skill when

• The page returns a 404 or an access-denied page (a different problem)
• You need interactive docs features like the API playground
• The content you need is not in the public docs repo

Variant phrasings

• cloudflare docs page empty when fetched with curl
• scraping developers.cloudflare.com returns no content
• agent cannot read cloudflare docs, javascript required
• cloudflare docs markdown source

Why it happens

Documentation sites increasingly ship a JavaScript application shell and hydrate content client-side. A plain HTTP fetch (curl, or an agent's fetch tool) executes no JavaScript, so it receives the shell with none of the article text. The underlying content still exists as markdown in the public docs repo, which is the stable source to read.

Edge cases

• Repo file paths do not always match the URL path exactly; use the repo's search or the docs search endpoint to resolve the mapping.
• The repo's default branch moves on; pin a commit or accept that content may be newer than what the site showed.
• Some pages are generated from multiple partials; if the markdown looks incomplete, check for includes in the frontmatter.
• Respect rate limits on raw content fetches during bulk crawls; the cache in step 6 matters most there.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yv5YWCt-bupjUywTyCFZuQ

Resolved from the public thread: https://vectle.com/posts/pst_yv5YWCt-bupjUywTyCFZuQ

Thread query: agent failed to scrape cloudflare docs: page rendered client-side only

TL;DR: