On this page:
2.1 Markdown source files
2.1.1 Post metadata
2.1.2 Markdown template files (experimental)
2.1.3 Code blocks in markdown files
2.2 Scribble source files
2.2.1 Pygments code blocks
pygment-code
2.3 Automatic post features

2 Posts

You create new posts in "_src/posts/". There are several source formats.

2.1 Markdown source files

Post source files in markdown format should be named "YYYY-MM-DD-TITLE.md" and need to have some metadata in the first few lines.

You can do raco darwin -n "My Title" to create such a file easily. This will also fill in the required metadata section. The markdown file starts with a code block (indented 4 spaces) that must contain these three lines.

    Title: A blog post

    Date: 2012-01-01T00:00:00

    Tags: foo, bar, tag with spaces, baz

    Authors: Alice Baker, Charlie Dean

 

Everything from here to the end is your post's contents.

 

If you put `<!-- more -->` on a line, that is the ``above-the-fold''

marker. Contents above the line are the ``summary'' for index pages

and Atom feeds.

 

<!-- more -->

 

Contents below `<!-- more -->` are omitted from index pages and Atom

feeds. A ``Continue reading...'' link is provided instead.

2.1.1 Post metadata
2.1.2 Markdown template files (experimental)

Files with a .mdt extension are first evaluated as Templates. The resulting text is fed to the markdown parser, as for a .md plain markdown source.

Such files may be used as the source for both posts and non-post pages.

There are no template variables — not even when the file is being used as the source of a post. The template evaluation occurs prior to the extraction of the post metadata.

2.1.3 Code blocks in markdown files

Darwin optionally uses Pygments to do syntax highlighting. Pygments has lexers for many, many languages. Plus, it fits the spirit of static web site generation better than JavaScript options like SyntaxHighlighter.

When using fenced code blocks, you can specify a language (as on GitHub):

```language

some lines

of code

```

That language is given to Pygments as the lexer to use.

The colors are controlled by your "css/pygments.css" file. There are examples of many styles.

If you use larger font sizes, code may wrap and get out of alignment with the line numbers. To avoid the wrapping, add the following to your "css/custom.css":

custom.css

/* When highlighted code blocks are too wide, they */

/* wrap -- resulting in the line numbers column's */

/* rows not lining up with the code rows. Prevent */

/* wrapping. */

pre {

    white-space: pre;

    width: inherit;

}

2.2 Scribble source files

Post source files in Scribble format should be named YYYY-MM-DD-TITLE.scrbl and need to have some Post metadata in the first few lines.

You can do raco darwin -N "My Title" to create such a file easily. This will also fill in the required metadata section.

See the example Scribble post and example Scribble non-post page for more information.

2.2.1 Pygments code blocks

 (require darwin/scribble) package: darwin

procedure

(pygment-code #:lang lang str ...)  paragraph?

  lang : string?
  str : string?
In Scribble source files of course you can use codeblock, racketblock, and friends to write code blocks for languages that have DrRacket style syntax-coloring parsers.

For other languages, you can emit a <pre> block with a language tag (as happens with Code blocks in markdown files) so that it can be highlighted by Pygments.

Example usage:

@(require darwin/scribble)

@pygment-code[#:lang "js"]{function foo() {return 1;}}

2.3 Automatic post features

Posts are automatically included in various index pages and feeds.

All posts go on the home page "/index.html", in an Atom feed "/feeds/all.atom.xml", and in an RSS feed "/feeds/all.rss.xml".

Posts for each tag go on an index page "/tags/<tag>.html", in an Atom feed "/feeds/<tag>.atom.xml", and in an RSS feed "/feeds/<tag>.rss.xml".

The default Post template provides:

The default Page template (used for all pages, not just post pages) also provides: