1 Quick start

Open DrRacket and start a new file like so:

"Untitled 1"

#lang punct
 
---
author: Me
---
 
# My first Punct doc
 
Simple.

Now click the Run button in the toolbar. Punct will parse the document and produce a document struct containing its metadata and an Abstract Syntax Tree (AST):

'#s(document #hasheq((author . "Me") (here-path . "7-unsaved-editor"))
             ((heading ((level 1)) "My first Punct doc") (paragraph "Simple."))
             ())

This value is automatically bound to doc. The metadata at the top is included in that value, but is also bound to metas.

> doc

'#s(document

    #hasheq((author . "Me") (here-path . "7-unsaved-editor"))

    ((heading ((level 1)) "My first Punct doc") (paragraph "Simple."))

    ())

> metas

'#hasheq((author . "Me") (here-path . "7-unsaved-editor"))

Both of these bindings are also provided so you can access them from other modules with require or dynamic-require.

You can render "doc" to HTML by passing it to doc->html. In the REPL:

> (require punct/render/html)
> (doc->html doc)

"<article><h1>My first Punct doc</h1><p>Simple.</p></article>"

You can escape to Racket code using the “bullet” character (U+2022):

#lang punct
 
Today we’re computing (+ 1 2).
 
string-upcase{keep it down, buddy.}

Punct does not care what extension you use for your filenames. Using ".rkt" is the simplest thing to do if you are using DrRacket, but you can use whatever you want. I use ".page.rkt" in my projects.

Any simple values produced by Racket code are converted to strings at compile time. If these strings contain valid Markdown, they will be parsed along with the rest of the document. The code below will produce a bulleted list:

#lang punct
 
Three things to remember:
 
(apply string-append
        (map (λ (s) (format "* ~a\n" (string-upcase s)))
             '("keep" "it" "down")))

Results in:

'#s(document #hasheq((here-path . "7-unsaved-editor"))
             ((paragraph "Three things to remember:")
                (itemization ((style tight) (start #f))
                             (item "KEEP")
                             (item "IT")
                             (item "DOWN")))
             ())