Writing posts¶
All of your posts will typically be contained in the posts
directory in
your main blog directory. Your post file can be called anything you want, and
as long as you’re not mixing and matching different text processors, the
file extension can be anything, too. I use the following naming convetion:
2011-07-29-name-of-post.rst
This way my posts are automatically ordered by publish date when I run ls
in the posts
directory.
Markdown, textile and HTML¶
When you’re writing your posts in Markdown (or textile or HTML), you need to add a bit of text to the top of your file to provide Socrates with some metadata about your post.
----------------------------------------------------------------------
title: Title of your post
date: 2011-07-29 13:00:00
categories:
- Photos
- Vacation
----------------------------------------------------------------------
The text between the two horizontal line is written in YAML syntax. Note that the horizontal line should have at least 79 characters.
reStructuredText¶
If you want to write your post in reStructuredText, you should use the rst native way to specify document metadata. Include this at the top of your post file:
:title: Title of your post
:date: 2011-07-29 13:00:00
:categories: Photos, Vacation
This way, your posts can be processed by the native Docutils utility
functions such as rst2html.py
or rst2latex.py
.
Options¶
-
title
¶
The title of the post
-
slug
(optional)
¶ The url-ized transformation of your title. This is useful if you need to maintain an existing url format.
-
date
¶
Publish date;
YYYY-MM-DD HH:MM
-
categories
¶
A list of categories
-
template
¶
You can override the default template that the post is going to be rendered with.
Syntax highlighting¶
Socrates has built-in support for syntax highlighting via pygments. It’s only available for the markdown and reStructuredText flavors.
Markdown¶
For markdown files, we use the same syntax as Github for specifying code blocks.
Paragraph text
```python
import datetime
print datetime.datetime.utcnow()
```
More text
reStructuredText¶
In reStructuredText, you can use the code-block
or sourcecode
directives.
Paragraph text
.. code-block:: python
import datetime
print datetime.datetime.utcnow()
More text