Skip to content

docs: merge the hand-written JSON-LD into Mintlify's node - #98

Merged
a-essawy merged 1 commit into
mainfrom
docs-jsonld-merge
Sep 18, 2026
Merged

a-essawy merged 1 commit into
mainfrom
docs-jsonld-merge

Conversation

@a-essawy

Copy link
Copy Markdown
Contributor

Every page carried two Article nodes for one URL. Mintlify generates a full @graph with @id .../slug#article; the hand-written block in each MDX used .../slug/#article — one slash apart, so nothing merged them.

Deleting them was the obvious fix and the wrong one

The hand-written block is the only source of datePublished and author; Mintlify emits neither. Aligning the @id merges the nodes instead — but doing only that would introduce two conflicts on the merged node, so all three changes go together:

change why
@id: drop the slash before #article the two nodes merge (30 pages)
remove dateModified static value vs Mintlify's live build-time one, which now also renders as the visible "Last modified on" stamp. Two values for one property on one node is a conflict.
remove isPartOf pointed at https://rendobar.com/#website — the apex WebSite node, which does not exist on a docs page. Mintlify already carries the correct isPartOf → /docs#website. (31 pages)

Net: one Article node per page instead of two, now carrying datePublished and author as well.

Two others

  • support/faq.mdx is an FAQPage, not an Article. Same trailing-slash @id, and the node was floating unconnected. Now matches the canonical form and points at Mintlify's WebPage node.
  • snippets/org-jsonld.mdx deleted. Nothing has ever imported it (grep finds it only in .git/index), and it declared a third Organization plus a fourth WebSite that would have conflicted with both graphs had anything used it.

Test plan

all five validators           PASS
@id base == canonical         32/32, zero mismatches

After merge, confirm one Article node per page in the rendered DOM.

Every page carried two Article nodes for one URL. Mintlify generates a full
@graph with @id ".../slug#article"; the hand-written block in each MDX used
".../slug/#article", one slash apart, so nothing merged them.

Deleting the hand-written block was the obvious fix and the wrong one. It is
the only source of datePublished and author, which Mintlify does not emit.
Aligning the @id merges the two instead, but naively doing that would have
introduced two conflicts on the merged node, so all three changes go together:

- @id: drop the slash before #article, so the nodes merge (30 pages)
- dateModified: removed. It was a static date, while Mintlify emits a live
  build-time value that now also renders as the visible "Last modified on"
  stamp. Two values for one property on one node is a conflict, not detail.
- isPartOf: removed. It pointed at https://rendobar.com/#website, the APEX
  WebSite node, which does not exist on a docs page. Mintlify's node already
  carries the correct isPartOf -> /docs#website. (31 pages, including the FAQ.)

Net: one Article node per page instead of two, now carrying datePublished and
author as well.

support/faq.mdx is the odd one out, an FAQPage rather than an Article. Its @id
had the same trailing slash and the node was floating unconnected, so it now
matches the canonical form and points at Mintlify's WebPage node.

snippets/org-jsonld.mdx is deleted. Nothing has ever imported it, and it
declared a third Organization plus a fourth WebSite that would have conflicted
with both graphs had anything used it.
@a-essawy
a-essawy merged commit fac3dc0 into main Sep 18, 2026
1 check passed
@a-essawy
a-essawy deleted the docs-jsonld-merge branch September 18, 2026 07:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant