Doing more than Markdown in Markdown authoring mode

Computational typesetting
1

I’m just discovering Pollen and I’d like to use it to create a API documentation with more features and abstraction than Markdown offers us.

Is it possible to write most of the text in Markdown and add features with Pollen? When I tried, it didn’t do what I expected:

#lang pollen

◊strong{foo}	
# some title

Produces:

'(root (p rsquo "(strong " ldquo "foo" rdquo ") # some title"))

but from the second tutorial, I expected:

'(root (strong "foo") (h1 ((id "some-title")) "some title"))

2

Yes, but you didn’t write the text in Markdown. Your example should be written like so:

#lang pollen/markdown

**foo**

# some title

And then the result is:

'(root (p (strong "foo")) (h1 ((id "some-title")) "some title"))
3

But that’s my question: can I do in Markdown what Markdown is capable of, and when I want to do something that Markdown is not capable of, switch to HTML/X-expressions?

In particular, I’d like to be able to insert links into example source code, which I can do in pre but not with Markdown.

4

In the Markdown dialect of Pollen, any in-line Racket code is first evaluated, the results get converted to strings, and then the whole thing is sent through the Markdown parser as the final step. Which means that ultimately, you cannot get a more “featureful” structured document out of the process than the Markdown parser is capable of producing. X-expressions in particular are also converted to strings, and these strings have no significance to the Markdown parser, which will just try and apply its “smart” typography to the single/double quotes in the string representation of the list.

In your example:

#lang pollen

◊strong{foo}	
# some title

The value strong isn’t bound to anything. In the Pollen environment, when you reference a binding that doesn’t exist, Pollen creates a procedure for it, and then calls that procedure with the arguments you gave ("foo"). That results in the value '(strong "foo") (see default-tag-function) which is what the Markdown parser sees.

If you have a pollen.rkt saved in the same folder, you can define strong yourself and Pollen will make use of it:

#lang racket

(provide strong)

(define (strong word-or-words)
  (format "**~a**" word-or-words))

Then your example will work the way you expect, because you’re adding formatting that the Markdown parser understands.

5

This discussion on the old pollen-users repo has some more good pointers on this issue too.

In particular, there is the HTML-in-Markdown hack that I thought of (second-to-last comment in that issue). I forgot about that until after I submitted my first reply above.

1 Like