▼Punct:   Common  Mark +   Racket
►4 Rendering
On this page:
4.1 Rendering HTML
doc->html
doc->html-xexpr
default-html-tag
4.2 Rendering plain text
doc->plaintext
make-plaintext-fallback
    contents  ← prev  up  next → 

4 Rendering

A Punct document is format-independent; when you want to use it in an output file, it must be rendered into that output file’s format.

Punct includes an HTML renderer and a plain-text renderer, and is designed to include renderers for more formats in the future.

4.1 Rendering HTML

 (require punct/render/html) package: punct-lib

procedure

(doc->html pdoc [fallback]) → string?

  pdoc : document?
  fallback : (-> symbol? list? list? xexpr?) = default-html-tag
Renders pdoc into a string containing HTML markup. Each custom element is passed to fallback, which must return an X-expression.

For more information on using the fallback argument to render custom elements, see Rendering custom elements.

procedure

(doc->html-xexpr pdoc [fallback]) → xexpr?

  pdoc : document?
  fallback : (-> symbol? list? list? xexpr?) = default-html-tag
Renders pdoc into HTML, but in X-expression form rather than as a string. Each custom element is passed to fallback, which must itself return an X-expression.

For more information on using the fallback argument to render custom elements, see Rendering custom elements.

procedure

(default-html-tag tag attributes elements) → xexpr?

  tag : symbol?
  attributes : (listof (listof symbol? string?))
  elements : list?
Returns an X-expression comprised of tag, attributes and elements. Mainly used as the default fallback procedure for doc->html.

Examples:
> (default-html-tag 'kbd '() '("Enter"))

'(kbd "Enter")

> (default-html-tag 'a '((href "http://example.com")) '("Link"))

'(a ((href "http://example.com")) "Link")

4.2 Rendering plain text

 (require punct/render/plaintext) package: punct-lib

Sometimes you want to convert a document into a text format that is even plainer than Markdown, such as when generating the plaintext version of an email newsletter.

procedure

(doc->plaintext pdoc line-width [fallback]) → string?

  pdoc : document?
  line-width : exact-nonnegative-integer?
  fallback : (symbol? (listof (listof symbol? string?)) list? . -> . string?)
   = (make-plaintext-fallback line-width)
Renders pdoc into a string of plain text, hard-wrapped to line-width characters (except for block-quotes, which are hard-wrapped to a length approximately 75% as long as line-width). Any custom elements are passed to fallback, which must return a string.

The function applies very rudimentary text formatting which usually looks as you would expect, but which often discards information.

For more information on using the fallback argument to render custom elements, see Rendering custom elements.

Examples:
> (require punct/render/plaintext)
> (define email (parse-markup-elements (hasheq) '("# Issue No. 1\n\nHowdy!")))
> (display (doc->plaintext email 72))

Issue No. 1

===========

Howdy!

procedure

(make-plaintext-fallback width)

 → (symbol? (listof (listof symbol? string?)) list? . -> . string?)
  width : exact-nonnegative-integer?
Returns a function that accepts three arguments (the tag, attributes and elements of an X-expression). Mainly used to create the default fallback procedure for doc->plaintext.

Examples:
> (define foo (make-plaintext-fallback 72))
> (foo 'kbd '() '("Enter"))

"[kbd] Enter\n\n"

> (foo 'a '((href "http://example.com")) '("Link"))

"[a] Link\n\n"

    contents  ← prev  up  next →