1 Quick start

Open DrRacket and start a new file like so:

"Untitled 1"

#lang punct

---

author: Me

---

# My first Punct doc

Simple.

As you can see, this document uses Markdown formatting and has a little metadata block near the beginning. It’s essentially a normal Markdown file, very much like one you would use with most publishing systems. The only thing that makes it different is the addition of #lang punct at the top.

Now click the Run button in the toolbar. Punct will parse the document’s Markdown content and metadata, and produce a document struct containing the 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")))

())