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.

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

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

• current-title

• current-author

• current-scheme/host

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

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.