3 Racket in Markdown

All of Polyglot’s built-in workflows turn a mix of Racket and Markdown into HTML5 documents. If you don’t want to use Markdown or HTML5, that’s perfectly fine. We’ll cover how to switch them up later. For now, using the built-in workflows will help you get started quickly while learning how to handle content with Polyglot.

One of Markdown’s nicer features is that you can use HTML elements directly inside of it. Polyglot’s built-in workflows take advantage of this by supporting new types of <script> elements that hold Racket code. There are library ("lib") elements and application ("app") elements. When a built-in workflow encounters these elements, it saves them to disk in a temporary directory that lasts only long enough to prepare the page.

3.1 Application Elements

Here’s an example from The Imperative Workflow. In this workflow, app elements write tagged X-expressions to replace the surrounding app element.

This would produce something like:

Here’s an equivalent example in The Functional Workflow, where an app element can replace the entire page without side-effects.

In either case, application elements can modify the Tagged X-Expression representing the page in which you are working. The intended experience is that you can stop writing at any time and make an incision into your page with an application element.

3.2 Library Elements

Library elements have media type "text/racket". Library elements are saved to disk before application elements run. This lets you share code and data within the page. Unlike app elements, library elements can provide any identifiers they wish just like any other Racket module.

Library elements do not operate differently across workflows.

Here’s a library element that provides a procedure for writing a custom HTML element as a Tagged X-Expression. This library can sit among prose just like any other element.

The id is important. When a workflow sees a library element, it will write it to disk next to other modules from application and library elements. This makes it easy to require the library.

3.3 Accessing Shared Content

Library elements provide shared content within a page. To share code and data across pages, place the goods in your project directory and use the generated project symlink to access them.

3.4 Addendum: Avoid Leaving XML in HTML5

Polyglot’s Markdown parser happens to include XML elements embedded in your page for processing. As you learn more about your workflow, you’ll find you can generate content in terms of those elements. This lets you write things like this and have it mean something:

But if you build a project with this markup, the page element will not appear because you forgot to close the elements, XHTML style. If you add the missing / before the >, it will work. You may safely omit the / for HTML5 void elements, however.

Since HTML5 is not based on XML, you need to take special care to transform any XML-based content you introduce for convenience back to valid HTML5 in the built-in workflows.