mdtopdf.

Document field notes

GitHub issue links in a Markdown PDF: cards vs plain URLs

How bare GitHub and GitLab links become reference cards in an exported PDF, what metadata they freeze, and when a plain link is the better choice.

Published 2026-10-24 · Markdown to PDF editorial

Paste a bare GitHub or GitLab issue URL into the editor and it can expand into a reference card: repository, number, state, title, author and date. That is useful in a review document and wasteful in a link list. The card is resolved from the live item when the document is rendered, so it records a moment that will not stay true.

What the converter documents

Markdown to PDF describes reference cards for bare GitHub and GitLab issue, pull-request and merge-request URLs, and link preview cards for other bare URLs built from the page's Open Graph tags. Its product notes also list settings for GitHub/GitLab links (preview card or plain URL) and for other links (plain URL or preview card). The card is a rendering choice, not a property of the URL itself.

A fixture with four kinds of link

# Links

Bare GitHub issue: https://github.com/commonmark/commonmark-spec/issues/10

Second GitHub issue: https://github.com/commonmark/commonmark-spec/issues/844

Bare site: https://example.com

Markdown link: [Example](https://example.com)

GitLab issue: https://gitlab.com/gitlab-org/gitlab/-/issues/1

What the checks showed

The fixture was opened in the live preview and exported as a one-page PDF on 24 October 2026. These are observations from that session, not a promise about every repository or viewer.

  • The GitHub URL became a card. The card showed GitHub, commonmark/commonmark-spec#10, the state "Closed", the title "Setext headers' fuzzy definition", the type "Issue", the author and the date. A second bare URL for an open issue rendered the same card shape with the state "Open".
  • The GitLab URL became a card too. It showed GitLab, gitlab-org/gitlab#1, "Closed", the title, the author and the date.
  • A Markdown link stayed a plain link. [Example](https://example.com) printed as underlined text, not a card.
  • A bare site URL stayed plain. https://example.com printed as a URL. A bare MDN URL also stayed plain in this check, so the generic preview card did not materialise for either page here; the product documentation describes that behaviour as depending on the page's metadata.
  • The cards survived export. The PDF printed both cards with their state labels. In greyscale the words "Open" and "Closed" remained readable even though the colour distinction disappeared. All five URLs had PDF link annotations.

Choose a card or a plain link

  1. Use a card when the issue is evidence. If the argument depends on which issue was closed, who reported it or what state it is in, the card carries that context into the PDF without the reader leaving the page.
  2. Use a plain link in a reference list. A page of cards is mostly chrome. Ten linked issues at the end of a document are easier to scan as a list, with the numbers and titles written out.
  3. Do not use cards for decoration. A card for a repository homepage or an unrelated article takes three or four lines and pulls attention away from the sentence. Link it normally.
  4. Keep one card per section at most. That is an editorial budget, not a product limit. Cards are visually heavy; several in a row turn the page into a dashboard.
  5. Write the sentence so the card has a job. "The regression was closed as fixed in the issue below" tells the reader why the card is there. A bare card followed by unrelated text makes them guess.
  6. Remember that the card is a snapshot. State, title and date reflect the item when the document was rendered. Add the export date in the surrounding text when the state matters, and re-export rather than editing the PDF later.

Check the card before sending

  1. Open the linked item. Confirm it is the issue or merge request you meant. A transposed number produces a confident-looking card for the wrong discussion.
  2. Read the state and title in the PDF. Confirm they match what you wrote in the sentence. "Closed" in the card next to "still open" in the prose is a contradiction the reader will notice.
  3. Check the card in greyscale. The state words should carry the meaning without colour. In the test they did; a card design that relies on a coloured dot alone would not.
  4. Click the card. The exported PDF should carry the destination. If the card is decorative but not a link, the reader cannot verify it.
  5. Check private links before sharing. A card can expose a title, author and state from a private repository, and the converter may request the linked resource when it renders the card. If the recipient should not see that metadata, convert the link to plain text or remove it. Check the tool's data-handling description if the URL is private.
  6. Check the settings. If cards are not wanted, switch GitHub/GitLab links to plain URLs before exporting instead of deleting and retyping every link.

Diagnose a card that did not appear

A full GitHub URL stayed plain
The URL may not be a recognised issue, pull-request or merge-request address, or the fetch failed. Use the canonical URL for the item and try again.
The card is wrong or stale
The card reflects the live item when the document is rendered. Re-export after the item changes, and state the export date in the document.
The card is too large for the page
Convert it to a normal Markdown link or change the link setting to plain URL. Cards are designed for emphasis, not for long lists.
Private repository links show no card
The document may not have access to the item, or the card fetch may be blocked. Do not rely on a card for access-controlled content; write the title and state in the text if the reader needs them.
The card disappeared in the PDF
Check the preview before exporting. If it is present there but absent in the file, try another viewer and confirm the URL had loaded when the card was rendered.
The reader cannot click the card
Check the PDF for link annotations. If the card is only an image, add a visible plain URL beside it.

Delivery checklist

  • Each card supports a sentence rather than replacing it.
  • Cards are limited to the few issues that are evidence, not every reference.
  • The issue number, title and state were checked against the live item.
  • The export date or version is stated where state matters.
  • No private metadata is exposed by a card the recipient should not see.
  • Cards remain legible in greyscale and still carry a clickable destination.
  • Long reference lists use plain links rather than cards.

Sources and scope

Checked 24 October 2026. The workflow is editorial guidance. Observations come from one desktop browser session and one one-page export on that date; no benchmark or cross-viewer audit is claimed. Repository states and titles are examples observed at that time and may have changed.