[DNS] Document shadowed records and shadow metadata

[matildeopbravo]

Summary

Adds a new DNS reference page documenting shadowed records and the shadow metadata API behavior.

The page explains what shadowed records are, covers glue and dead glue records, and documents the shadow metadata fields (shadowed_by, is_glue, dead_glue, shadowed_records_count) along with how to request them.

Documentation checklist

• Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
• The change adheres to the documentation style guide.
• If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/dns/	@RebeccaTamachiro, @hannes-cf, @cloudflare/product-owners, @esomoza-cf, @fattouche, @xofyarg, @dklbreitling, @chreo, @svenr-cf, @kerolasa, @matildeopbravo, @vavrusa, @mworsley-cloudflare, @sebastiaanyn, @vendemiat, @Woutifier

[ask-bonk]

Verdict: 5 style issues need fixing before merge. No build breakers.

Issues:

• HIGH (line 28): ns1.externalprovider.com is not a reserved example domain and could resolve to a live origin. Replace with ns1.example.org.
• MEDIUM (line 4): description exceeds the 160-character limit. Shorten to stay within the style guide range.
• MEDIUM (line 9): H1 heading in body content duplicates the frontmatter title. Remove it to match other pages in this directory.
• LOW (line 20): Directional language (below) and See should be Refer to.
• LOW (lines 171, 180): Placeholders <ns-record-id> should be <NS_RECORD_ID> (uppercase, underscores) per non-API placeholder conventions.

Note: Consider adding products:\n - dns to frontmatter for consistency with sibling reference pages. The changelog checkbox is unchecked — if include_shadow_metadata is new API behavior, add a changelog entry.

[ask-bonk]

I have completed the review of PR #31731. Here's a summary of what I did:

Labels applied: product:dns, documentation, content:new, triage

Review summary: I posted a review comment with 5 inline suggestions/comments. The PR introduces a well-structured DNS reference page for shadowed records and shadow metadata. The main issues I flagged are:

• HIGH (line 28): ns1.externalprovider.com is not a reserved example domain and could resolve to a live origin.
• MEDIUM (line 4): The description field exceeds the 160-character style guide limit.
• MEDIUM (line 9): There is an H1 heading in the body content, which duplicates the frontmatter title and doesn't match other pages in the directory.
• LOW (line 20): Directional language (below) and See should be Refer to.
• LOW (lines 171, 180): Placeholders <ns-record-id> should use uppercase/underscore format (<NS_RECORD_ID>).

I also noted that the author should consider adding products: - dns for consistency, and check whether a changelog entry is needed for the new include_shadow_metadata API behavior documentation.

github run

[github-actions]

Preview URL: https://27afc7b6.preview.developers.cloudflare.com
Preview Branch URL: https://matilde-shadowed-records-clarify.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records/	https://matilde-shadowed-records-clarify.preview.developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records/