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 frog -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
Title can be anything.
Date must be an ISO-8601 datetime string: yyyy-mm-ddThr:mn:sc.
Tags is optional. The tag DRAFT (all uppercase) causes the post HTML file not to be generated.
Authors is optional. When present, this overrides the default Author in your frog.rkt.
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 —
2.1.3 Code blocks in markdown files
Frog 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 frog -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 frog/scribble) | package: frog |
procedure
(pygment-code #:lang lang str ...) → paragraph?
lang : string? str : string?
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.
@(require frog/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:
Twitter and Google+ sharing buttons.
Disqus comments.
The default Page template (used for all pages, not just post pages) also provides:
Twitter follow button.
Google Analytics tracking.