resolve_anchor_links: Resolve Reference-Style Links

In ropensci/tinkr: Cast '(R)Markdown' Files to 'XML' and Back Again

Resolve Reference-Style Links

Description

Reference style links and images are a form of markdown syntax that reduces duplication and makes markdown more readable. They come in two parts:

1. The inline part that uses two pairs of square brackets where the second pair of square brackets contains the reference for the anchor part of the link. Example:

   [inline text describing link][link-reference]
   

2. The anchor part, which can be anywhere in the document, contains a pair of square brackets followed by a colon and space with the link and optionally the link title. Example:

   [link-reference]: https://docs.ropensci.org/tinkr/ 'documentation for tinkr'
   

Commonmark treats reference-style links as regular links, which can be a pain when converting large documents. This function resolves these links by reading in the source document, finding the reference-style links, and adding them back at the end of the document with the 'anchor' attribute and appending the reference to the link with the 'ref' attribute.

Usage

resolve_anchor_links(body, txt, ns = md_ns())

Arguments

body	an XML body
txt	the text of a source file
ns	an the namespace that resolves the Markdown namespace (defaults to md_ns())

Details

Nomenclature

The reference-style link contains two parts, but they don't have common names (the markdown guide calls these "first part and second part"), so in this documentation, we call the link pattern of ⁠[link text][link-ref]⁠ as the "inline reference-style link" and the pattern of ⁠[link-ref]: <URL>⁠ as the "anchor references-style link".

Reference-style links in commonmark's XML representation

A link or image in XML is represented by a node with the following attributes

• destination: the URL for the link

• title: an optional title for the link

For example, this markdown link ⁠[link text](https://example.com "example link")⁠ is represented in XML as text inside of a link node:

lnk <- "[link text](https://example.com 'example link')"
xml <- xml2::read_xml(commonmark::markdown_xml(lnk))
cat(as.character(xml2::xml_find_first(xml, ".//d1:link")))
#> <link destination="https://example.com" title="example link">
#>   <text xml:space="preserve">link text</text>
#> </link>

However, reference-style links are rendered equivalently:

lnk <- "
[link text][link-ref]

[link-ref]: https://example.com 'example link'
"
xml <- xml2::read_xml(commonmark::markdown_xml(lnk))
cat(as.character(xml2::xml_find_first(xml, ".//d1:link")))
#> <link destination="https://example.com" title="example link">
#>   <text xml:space="preserve">link text</text>
#> </link>

XML attributes of reference-style links

To preserve the anchor reference-style links, we search the source document for the destination attribute proceded by ⁠]: ⁠, transform that information into a new link node with the anchor attribute, and add it to the end of the document. That node looks like this:

<link destination="https://example.com" title="example link" anchor="true">
  <text>link-ref</text>
</link>

From there, we add the anchor text to the node that is present in our document as the ref attribute:

<link destination="https://example.com" title="example link" rel="link-ref">
  <text xml:space="preserve">link text</text>
</link>

Note

this function is internally used in the function to_xml().

Examples

f <- system.file("extdata", "link-test.md", package = "tinkr")
md <- yarn$new(f, sourcepos = TRUE, anchor_links = FALSE)
md$show()
if (requireNamespace("withr")) {
lnks <- withr::with_namespace("tinkr", 
  resolve_anchor_links(md$body, readLines(md$path)))
md$body <- lnks
md$show()
}

ropensci/tinkr documentation built on April 23, 2024, 9:41 a.m.