The Pollen Cookbook

Paragraphs

In other markup languages like Markdown, double newlines are treated as paragraph separators by default. But in Pollen, paragraphs don’t get marked up for you automatically: you have to decide how you want this handled.

The most common way: do it in your root function using a call to decode or decode-elements and passing it the decode-paragraphs function:  + The relevant explainer in the Pollen docs is part 7.7.

#lang pollen

(require pollen/decode)

(define (root . elements)
  `(main ,@(decode-elements elements
                            #:txexpr-elements-proc decode-paragraphs
                            #:exclude-tags '(pre))))

Note that you can exclude automatic paragraph wrapping within certain tags by supplying a list of tags in the #:exclude-tags argument. The pre tag is commonly excluded this way since it is often used for code samples.

Hard-wrapped paragraphs

Using the approach above, you will find that any line breaks within your paragraphs get converted to br tags, making them equivalent to hard line breaks in the rendered HTML.

This is because, by default, decode-paragraphs function calls decode-linebreaks without specifying what to substitute for any line breaks it finds. And decode-linebreaks in turn defaults to the br tag.

You can change this behavior by wrapping decode-linebreaks in your own helper function that specifies a different substitution, then passing this helper function to decode-elements:

#lang pollen

(require pollen/decode)

(define (hardwrapped-grafs xs)
  (define (newline-to-space xs)
    (decode-linebreaks xs " "))
  (decode-paragraphs xs #:linebreak-proc newline-to-space))

(define (root . elements)
  `(main ,@(decode-elements elements
                            #:txexpr-elements-proc hardwrapped-grafs
                            #:exclude-tags '(pre))))

The above code converts single line breaks to space characters instead of converting them to br tags, so lines that are hard-wrapped in the Pollen source file become soft-wrapped in the HTML output.

Why do I sometimes not get a <p> tag in my HTML output?

The decode-paragraphs function determines which elements to wrap inside a paragraph block by finding those that are either separated by a double newline, or adjacent to block-level elements. So if your document contains only a single implicit paragraph, it will have neither of those things. To guarantee that decode-paragraphs wraps everything in at least a single paragraph tag, you must use the #:force? #t option:

#lang pollen

(require pollen/decode)

(define (hardwrapped-grafs xs)
  (define (newline-to-space xs)
    (decode-linebreaks xs " "))
  (decode-paragraphs xs #:linebreak-proc newline-to-space #:force? #t))

(define (root . elements)
  `(main ,@(decode-elements elements
                            #:txexpr-elements-proc hardwrapped-grafs
                            #:exclude-tags '(pre))))