On macOS you will need to add /Applications/Racket\ 7.0/bin (or similar) to your PATH in order to be able to run things like racket or raco at the command line.
- Install Darwin:
$ raco pkg install darwin
Optional: If you want syntax highlighting for fenced code blocks:
To update Darwin and its dependencies:
$ raco pkg update --update-deps darwin
Creating a new blog project is 3 easy steps:
- Create a subdirectory.
$ mkdir darwin-project
- Go there.
$ cd darwin-project
- Tell Darwin to create default files and directories.
$ raco darwin --init
Creating files in /tmp/darwin-project/:
Project ready. Try `raco darwin -bp` to build and preview.
You can go ahead and build/preview this to get a feel for the default starting point:
$ raco darwin -bp
Launching /usr/bin/python pipe.py
Your Web application is running at http://localhost:3000/index.html.
Stop this program at any time to terminate the Web Server.
Web Server stopped.
Here is the file tree that raco darwin --init creates for you and Darwin expects:
# Files provided by you:
darwin.rkt # darwin.rkt
page-template.html # entire page layout: Page template
post-template.html # <article> layout: Post template
index-template.html # index pages: Index template
# You’ll create these using raco darwin -n <post-title>
# Zero or more other .md files, for non-post pages.
# May be in subdirs.
bootstrap.min.css # get these files
bootstrap.min.css.map # from https://getbootstrap.com
pygments.css # style code elements from Pygments
custom.css # other styles you provide; may be empty
jquery-3.2.1.slim.min.js # local copy of jQuery for Bootstrap
bootstrap.bundle.min.js # from https://getbootstrap.com/
Here are the files created by Darwin when you run raco darwin -b to (re)build the blog:
.darwin/build # a cache to support minimal rebuilds
# Post pages are in subdirs.
Although the Darwin example project has copies for example purposes, for your own project you should get the official/latest Bootstrap 4 files directly from Bootstrap.
For examples of "pygments.css" code highlighting styles see https://github.com/richleland/pygments-css.
When you used raco darwin --init it created a "darwin.rkt" file in your project directory. If you upgrade from an older version of Darwin that used a ".darwinrc" file: The first time the newer version of Darwin runs, it automatically creates an equivalent "darwin.rkt" from your ".darwinrc". Thereafter the ".darwinrc" is ignored, and may be deleted.
Your "darwin.rkt" lets you use simple Racket code to configure and customize your blog.
|#lang darwin/config||package: darwin|
Furthermore, the darwin/config language ensures that you define three functions that are used by Darwin:
(init) → any
You can set various parameters provided by darwin/params. To start, you might only need to set a few:
(clean) → any
A typical workflow:
1. Create a new post with raco darwin -n "My Post Title". The name of the new .md file is displayed to stdout.
2. Edit the .md file in your preferred plain text editor.
3. Regenerate your site and preview it with raco darwin -bp. (You might repeat steps 2 and 3 a few times until you’re satisfied.)
4. Deploy. If you’re using GitHub Pages, you can commit and push to update your site. If you’re using some other method, you can copy or rsync the files to your static file server.