Skip to content

docs: replace <cite> tag references with [N] numeric marker format#346

Merged
bensonwong merged 5 commits intomainfrom
docs/replace-cite-tags-with-numeric-markers
Mar 16, 2026
Merged

docs: replace <cite> tag references with [N] numeric marker format#346
bensonwong merged 5 commits intomainfrom
docs/replace-cite-tags-with-numeric-markers

Conversation

@bensonwong
Copy link
Collaborator

@bensonwong bensonwong commented Mar 16, 2026 •
edited
Loading

Summary

  • Removes all remaining references to the old XML <cite> tag citation format from public docs and framework guides
  • Updates prose and inline code comments to reflect the current [N] numeric marker + <<<CITATION_DATA>>> block format used by getAllCitationsFromLlmOutput and parseCitationResponse
  • Files changed: docs/index.md, docs/getting-started.md, docs/frameworks/langchain.md, docs/frameworks/nextjs.md, docs/frameworks/vercel-ai-sdk.md
  • Also bumps docs/agents/repo-map.md and docs-site-map.md to HEAD via /reindex (picks up new src/docs/ and examples/static-html/ dirs, corrects parsing/ description)

Test plan

  • Read each changed doc file and confirm no <cite> tag references remain in prose or comments
  • Verify the updated wording accurately describes <<<CITATION_DATA>>> block behavior for streaming guides (vercel-ai-sdk, nextjs)
  • Confirm docs/agents/repo-map.md SHA matches current HEAD (9e9dcbb)

Benson and others added 2 commits March 16, 2026 16:26
@claude
docs: replace <cite> tag references with current [N] numeric marker f…
004cfa2 
…ormat

The XML <cite> tag format was removed in favor of numeric [N] markers
with a <<<CITATION_DATA>>> JSON block. Updated all prose/comments that
still referenced the old format across 5 doc files.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@claude
chore: refresh agent index (repo-map + docs-site-map to HEAD 9e9dcbb)
cc91bfa 
Picks up new src/docs/ and examples/static-html/ directories, corrects
parsing/ description, and bumps staleness tracking to current commit.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@github-actions
Copy link
Contributor

github-actions bot commented Mar 16, 2026 •
edited
Loading

📚 Documentation Preview

The documentation has been built successfully.

To preview locally:

  1. Download the github-pages artifact from this workflow run
  2. Extract and serve with any static file server: 
    cd artifact && python -m http.server 8000
  3. Open http://localhost:8000/deepcitation/

⚠️ Link Check Results

Click to expand link check report

Summary

Status Count
🔍 Total 392
✅ Successful 337
⏳ Timeouts 0
🔀 Redirected 0
👻 Excluded 20
❓ Unknown 0
🚫 Errors 35

Errors per input

Errors in docs/_site/curl-guide.html

Errors in docs/_site/frameworks/index.html

Errors in docs/_site/getting-started.html

Errors in docs/_site/index.html

Errors in docs/_site/frameworks/langchain.html

Errors in docs/_site/styling.html

Errors in docs/_site/404.html

Errors in docs/_site/api-reference.html

Errors in docs/_site/CONTRIBUTING.html

Errors in docs/_site/components.html

Errors in docs/_site/error-handling.html

  • [404] https://fonts.googleapis.com/ | Failed: Network error: Not Found
  • [404] https://fonts.gstatic.com/ | Cached: Error (cached)
  • [ERR] file:///home/runner/work/deepcitation/deepcitation/docs/_site/styling.md | Failed: Cannot find file
  • [ERR] file:///home/runner/work/deepcitation/deepcitation/docs/_site/api-reference.md | Failed: Cannot find file
  • [ERR] file:///home/runner/work/deepcitation/deepcitation/docs/_site/getting-started.md | Failed: Cannot find file

Errors in docs/_site/code-examples.html

Errors in docs/_site/verification-statuses.html

Errors in docs/_site/types.html

Errors in docs/_site/frameworks/vercel-ai-sdk.html

Errors in docs/_site/frameworks/nextjs.html

Workflow run: 23139520707

@claude
Copy link

claude bot commented Mar 16, 2026

PR Review: docs: replace <cite> tag references with [N] numeric marker format

Overall this is a clean, focused docs cleanup that correctly aligns public-facing documentation with the current citation format. Good scope discipline — only the files that needed updating were touched.

✅ What's good

  • The streaming explanation in nextjs.md and vercel-ai-sdk.md is now more precise and accurate: emphasizing that <<<CITATION_DATA>>> arrives at the end of the stream is the key invariant users need to understand for correct integration.
  • getting-started.md and index.md step-3 descriptions now correctly name parseCitationResponse explicitly, which is more actionable for new users.
  • The repo-map.md and docs-site-map.md updates correctly reflect HEAD (9e9dcbb) and the new directories added since the last reindex.

⚠️ One inaccuracy to fix

docs/frameworks/langchain.md, line 101 comment:

-//    getAllCitationsFromLlmOutput parses <cite> tags from the LLM response.
+//    getAllCitationsFromLlmOutput parses numeric [N] markers from the LLM response's <<<CITATION_DATA>>> block.

This conflates two distinct parts of the format:

  • [N] markers appear inline in the LLM's prose (e.g., "The sky is blue [1]").
  • <<<CITATION_DATA>>> is a separate block appended at the end that contains the structured citation data.

getAllCitationsFromLlmOutput primarily parses the <<<CITATION_DATA>>> block — the [N] markers are for display/rendering, not for extraction. A more accurate comment:

//    getAllCitationsFromLlmOutput extracts citations from the <<<CITATION_DATA>>> block
//    appended at the end of the LLM response. The [N] inline markers reference these citations.

Minor notes

  • repo-map.md: The two new entries (src/docs/ # (no description) and examples/static-html/ # (no description)) are fine as auto-generated stubs, but if these directories have a clear purpose it would be worth adding a one-liner description so agents don't skip them. Non-blocking.
  • repo-map.md: parseCitationResponse was removed from the parsing/ description and replaced with normalizeCitation. Worth confirming this rename is accurate relative to the current exports — if parseCitationResponse still exists as a public API (it's referenced in the updated getting-started.md and index.md), it should remain in the description.

Test plan coverage

The PR's test plan is read-only verification, which is appropriate for a docs PR. No functional changes means no automated tests needed here.

Summary: Approve once the langchain.md comment precision issue is addressed. The rest of the changes are accurate and improve documentation clarity.

@github-actions
Copy link
Contributor

github-actions bot commented Mar 16, 2026 •
edited
Loading

✅ Playwright Test Report

Status: Tests passed

📊 Download Report & Snapshots (see Artifacts section)

What's in the Visual Snapshots

The gallery includes visual snapshots for:

  • 🖥️ Desktop showcase (all variants × all states)
  • 📱 Mobile showcase (iPhone SE viewport)
  • 📟 Tablet showcase (iPad viewport)
  • 🔍 Popover states (verified, partial, not found)
  • 🔗 URL citation variants

Run ID: 23139520628

Benson and others added 3 commits March 16, 2026 16:52
@claude
docs: update Full Integration Example to current API (prepareAttachme…
f9809dd 
…nts + verifyAttachment)

Replaces deprecated uploadFile/verify with prepareAttachments/verifyAttachment.
Fixes attachmentId destructuring (now from fileDataParts[0].attachmentId).
Adds React render step to getting-started showing parseCitationResponse/markerMap
pattern matching IntegrateSection RENDER_CODE.
Updates index.md Quick Install snippet to match.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@claude
docs: add contributor-facing BRANDING.md at package root (B6a)
47a7ab7 
Creates packages/deepcitation/BRANDING.md with a clean, audience-appropriate
sub-brand guide for GitHub contributors: color tokens, customization examples,
typography rules, and key contributor rules.

The existing docs/agents/branding.md (agent/implementation-focused) is kept
intact and cross-linked. The new root file covers only the public surface
(--dc-* tokens, DeepCitationTheme, font/radius rules) without internal
implementation details.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@claude
fix(readme): fix black-on-black logos in GitHub dark mode
c084900 
Uses <picture> + prefers-color-scheme to swap to brand-color variants
(logos/color/) in dark mode. OpenAI → #10A37F, Anthropic → #D4A27F,
Google → #4285F4. Vercel's color variant is also black so adds a
white SVG (docs/assets/vercel-white.svg) and references it via
raw.githubusercontent.com for the dark-mode srcset.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@bensonwong bensonwong merged commit 9472b0f into main Mar 16, 2026
11 checks passed
@bensonwong bensonwong deleted the docs/replace-cite-tags-with-numeric-markers branch March 16, 2026 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bensonwong