On this page:
1.1 Installing Darwin
1.2 Updating Darwin
1.3 Starting a new blog project
1.3.1 Project file tree
1.3.2 darwin.rkt
1.4 Creating blog posts

1 Quick start

1.1 Installing Darwin

  1. Install Racket.

    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.

  2. Install Darwin:

    $ raco pkg install darwin

  3. Optional: If you want syntax highlighting for fenced code blocks:

    1. Install the latest version of Python.

    2. Install Pygments:

      $ python3 -m pip install pygments

1.2 Updating Darwin

To update Darwin and its dependencies:

$ raco pkg update --update-deps darwin

1.3 Starting a new blog project

Creating a new blog project is 3 easy steps:

  1. Create a subdirectory.

    $ mkdir darwin-project

  2. Go there.

    $ cd darwin-project

  3. Tell Darwin to create default files and directories.

    $ raco darwin --init

    Creating files in /tmp/darwin-project/:

    /tmp/darwin-project/darwin.rkt

    /tmp/darwin-project/_src/About.md

    /tmp/darwin-project/_src/page-template.html

    /tmp/darwin-project/_src/post-template.html

    /tmp/darwin-project/_src/posts/2012-01-01-a-2012-blog-post.md

    /tmp/darwin-project/css/

    /tmp/darwin-project/js/

    /tmp/darwin-project/img/

    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

darwin 0.1

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.

  C-c C-c

Web Server stopped.

1.3.1 Project file tree

Here is the file tree that raco darwin --init creates for you and Darwin expects:

project/

  # Files provided by you:

  darwin.rkt      # darwin.rkt

  _src/         # default; see current-source-dir in darwin.rkt

    page-template.html  # entire page layout: Page template

    post-template.html  # <article> layout: Post template

    index-template.html # index pages: Index template

    posts/

      # You’ll create these using raco darwin -n <post-title>

      2013-01-01-a-blog-post.md

      2013-02-15-another-blog-post.md

      ...

    # Zero or more other .md files, for non-post pages.

    # May be in subdirs.

  css/

    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

    scribble.css

  js/

    jquery-3.2.1.slim.min.js # local copy of jQuery for Bootstrap

    bootstrap.bundle.min.js  # from https://getbootstrap.com/

  img/

    feed.png

  favicon.ico

Here are the files created by Darwin when you run raco darwin -b to (re)build the blog:

project/  # default; see current-output-dir in darwin.rkt

  .darwin/build   # a cache to support minimal rebuilds

  index*.html

  sitemap.txt

  tags/

  feeds/

  # Post pages are in subdirs.

  # Exact layout depends on current-permalink in darwin.rkt.

  blog/

    2013/

      01/

        a-blog-post-title/

          index.html

        ...

    2013/

      02/

        another-blog-post-title/

          index.html

        ...

  ...

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.

To design a Bootstrap 4 "theme", try Bootstrap Magic. Also, http://bootswatch.com/ has some ready-made themes.

For examples of "pygments.css" code highlighting styles see https://github.com/richleland/pygments-css.

1.3.2 darwin.rkt

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

The darwin/config language provides bindings from:

Furthermore, the darwin/config language ensures that you define three functions that are used by Darwin:

procedure

(init)  any

This is called once, early when Darwin starts.

You can set various parameters provided by darwin/params. To start, you might only need to set a few:

procedure

(enhance-body xs)  (listof xexpr/c)

  xs : (listof xexpr/c)
This is called for each post or non-post page, giving you the opportunity to modify the xexpr?s representing the content.

You may call functions provided by darwin/enhance-body. You may also require and use functions provided by a third-party package.

procedure

(clean)  any

Called during raco darwin --clean.

1.4 Creating blog posts

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.