Skip to contents

Writes each node as CommonMark text, for reading, for notes, or as input to a language model. Text is skipped and collapsed as html_text_clean() does, and Markdown-significant characters in it are escaped, so the text reads back as written.

Usage

html_markdown(x)

Arguments

x

A zuhtml_document or zuhtml_nodeset.

Value

A character vector as long as x: the Markdown of each element, document, fragment or text node, without a trailing newline; NA for other nodes and for missing nodes.

Details

The conversion covers:

  • headings (# to ######), paragraphs and the other block elements (separated by blank lines), and thematic breaks (<hr>, as ---, or as *** where it opens a - list item);

  • emphasis (<em>, <i>) as *...* and strong (<strong>, <b>) as **...**, where CommonMark reads it back as written: emphasis that cannot be written safely, such as emphasis inside emphasis of its kind, or bold italics of one element (written as **...**), keeps its text without the markup;

  • inline code (<code>, <kbd>, <samp>, <tt>) as a code span, with whitespace at its ends written outside it; adjacent spans join into one;

  • <pre> as a fenced code block, with its language when a language-* or lang-* class names one;

  • block quotes, and ordered and unordered lists, nested, with start, reversed and value honoured; empty list items are left out and take no number. A list right after another of its kind takes the other bullet (- or *) or delimiter (. or )), so that the two stay separate;

  • links and images, their URLs resolved against the document's base URL as html_url() does, or as written where that is not possible; <a> without href is plain text, and <img> without src is left out;

  • <br> as a hard line break;

  • data tables as GFM pipe tables: tables in which no cell spans rows or columns and every cell holds only inline content (no paragraphs, lists, headings, <div>s, code blocks or tables). Rows are in html_table()'s order (head, bodies, foot), the first is the header row, and cell contents stay on one line. Other tables, such as tables used for page layout, are written as their content, one paragraph per row, with cells separated by spaces.

<head>, <script>, <style>, <template>, <iframe>, <svg> and comments are left out. Other elements contribute their text only. Markup that crosses block boundaries, such as <b> around two paragraphs, is closed and reopened in each block.

Examples

doc <- html_parse(paste0(
  "<h1>Release notes</h1>",
  "<p>Version <b>2.0</b> adds <code>fetch()</code>. ",
  "See <a href='changes.html'>the changes</a>.</p>",
  "<ul><li>Faster parsing</li><li>New <i>options</i>:",
  "<ol><li>limits</li><li>encoding</li></ol></li></ul>",
  "<table><tr><th>Item</th><th>Cost</th></tr>",
  "<tr><td>Tea</td><td>3</td></tr></table>"
), base_url = "https://example.org/docs/")
cat(html_markdown(doc))
#> # Release notes
#> 
#> Version **2.0** adds `fetch()`. See [the changes](https://example.org/docs/changes.html).
#> 
#> - Faster parsing
#> - New *options*:
#>   1. limits
#>   2. encoding
#> 
#> | Item | Cost |
#> | --- | --- |
#> | Tea | 3 |