On this page:
2.1 Step 1:   Start Your Project
2.2 Step 2:   Write Content
2.3 Step 3:   Publish
2.4 So What?

2 Get Started

To confirm that everything works, install the package and run the demo command.

  $ raco pkg install polyglot

  $ polyglot demo

If the command succeeds, then you will see a dist folder appear in your working directory containing a README.html file. This is a distribution built from the README in the source code.

If the command fails, Polyglot is probably unable to create symbolic links. It needs symbolic links to function (See make-file-or-directory-link). On current versions of Windows, you may need to give an account permission to create links. If it’s just not working and you need help, open an issue.

2.1 Step 1: Start Your Project

Run this command to start a new project.

  $ polyglot start my-website

You’ll see a new directory called my-website. It has some starter code to play with.

2.2 Step 2: Write Content

The development server is for just that: development. Do not use it on production systems.

The develop command starts a local development server and rebuilds your website in response to changes in assets. Let it run in another terminal.

  $ polyglot develop my-website

Open up one of the Markdown files and make some changes. Break the code in it, and watch what happens. While the develop command is active, it will build only the assets relevant to your change. The distribution directory will update with new files as you go.

Building the website once is just as easy, if you need to spot-check something.

  $ polyglot build my-website

2.3 Step 3: Publish

Once you’re ready, just copy your distribution directory. If it helps, polyglot includes a command to rebuild your website and push the distribution to an S3 bucket.

  $ polyglot publish --region us-east-2 my-website my-bucket

For more details on what exactly this does, see polyglot publish: Publish to S3

2.4 So What?

Once again we see that Markdown + CSS = styled HTML. Snore.

Except hold on: If you look at the Markdown, you’ll find it has <script> elements containing code from... different Racket languages? You’ll also notice that something is crawling the source code, since there’s no import or something pulling in new pages. The output pages actually have layouts, but there’s no templating engine. On top of it all, this isn’t even an extended Markdown. In fact, this isn’t even using all of the features of the Daring Fireball spec.

This is where we start seeing where Polyglot is unique. It can tease out useful features despite being given so little to work with.

On its own, Polyglot has no idea how to process content. It needs a workflow to define what assets the website supports, and what happens to those assets when you build the project. It gives you room to extend languages arbitrarily to contain cooperating Racket modules, and it just so happens to use Markdown as a familiar prose language to "host" programs.

You’ll notice there’s a hidden .polyglotrc.rkt file in your project directory. Let’s open it up:


#lang racket/base
(require polyglot)
(provide (rename-out [polyglot/imperative% polyglot+%]))

Don’t worry if the workflow isn’t ideal. It’s not hard to change it later.

This module provides a workflow as polyglot+%, which is just a class. This configuration tells Polyglot to use The Imperative Workflow, which exists in code as polyglot/imperative%.

Before we dive deep into the Imperative Workflow, we’re going to talk about what has happened to the Markdown code.