Posts¶

Posts are the bread and butter of an Engineer site. Posts are Markdown files with either a .md or .markdown file extension and are structured like this:

title: What's Next?
timestamp: 09:41 AM Friday, March 09, 2012 PST
status: published
tags:
- example
- sample
slug: what-s-next


---

So what should you do now that you have created a sample Engineer site?

Posts are typically stored in a folder called posts within your site’s source directory, but you can put them anywhere - even in multiple folders - by changing the POST_DIR setting.

Everything above the --- is Metadata, and everything below it is the post itself (in Markdown, of course).

Metadata¶

Posts should contain some metadata that tells Engineer about the post. This metadata must be in YAML format, and must be the first thing in your post file. The YAML document separator (---) separates the post content and metadata.

None of the metadata is strictly required since there are defaults for everything but you must have at least one piece of metadata in your post file. In addition, Engineer will automatically update the metadata in your source post file during a build. This behavior is customizable; see the Metadata Finalization plugin for more information.

Changed in version 0.3.0: The metadata can now have a YAML document separator (---) above it as well as below it. This format is used by Jekyll, and by extension, Octopress, so posts written for those systems will migrate to Engineer without problems.

Metadata Parameters¶

title: The title of the post. If you don’t provide this, engineer will try to generate one based on the name of your post file, replacing any dashes or underscores in the file name with spaces. For example, if your post file is named A-Day-In-the-Life.md, Engineer will set the post title to ‘A Day In the Life’ unless you explicitly define a title in the post metadata.

timestamp: The date and time that the post is/was published. The format of the date and time has pretty loose requirements, but in general it’s best to follow this basic format: 2012-03-21 13:43:04. The timestamp can be a future time, in which case the post will not become published until that time. If you don’t provide an explicit timestamp, Engineer will set it to the date and time that the site is next built.

Note

Unless you specifically provide a timezone offset in your timestamp value, the time will be assumed to be in the same time zone as your POST_TIMEZONE setting.

See also

A Note About Timezones

status

The status of the post. Valid values are:

draft: Draft posts are never output when a site is built. Status always defaults to draft if it’s missing or set to an unknown value to avoid accidentally publishing something that wasn’t meant to be published.
published: Published posts are always output when a site is built unless they have a timestamp in the future, in which case they are not output. This behavior can be customized using the PUBLISH_PENDING setting.
review: Posts marked review are only output if the setting PUBLISH_REVIEW is set to true.

New in version 0.3.0.

Custom Metadata¶

In addition to the metadata properties listed above, each post can include other custom metadata, specified in YAML just like regular metadata. Engineer will add these custom properties to the Post’s custom_properties property, where they can be used by themes or plugins.

Custom properties are not manipulated in any way by Engineer itself (though plugins may change/update them) and they are maintained during Metadata Finalization.

A Note About Timezones¶

Time zones are a tricky thing in the best of circumstances, and unfortunately one of Python’s few weaknesses is how it deals with them. It’s particularly difficult to get the current system time zone, especially on Windows, so Engineer forces you to set a time zone explicitly. If you don’t, Engineer assumes that times are in UTC. You can use the POST_TIMEZONE setting to set which timezone Engineer should assume your post timestamps are in.

You can see a complete list of the valid timezone settings at the PostgreSQL site. Yes, it’s a bit weird, but the list there is the most comprehensive one I’ve seen that doesn’t threaten to utterly confuse and overwhelm mere mortals when they see it. Keep in mind that some rows in the table list multiple valid strings that happen to correspond to the same time zone. For example, Asia/Jerusalem, Asia/Tel_Aviv, and Israel all correspond to the same timezone, and all are valid strings. (Why they could not simply put a delimiter other than a space between the strings in a single row I’ll never understand.)

You can also choose to put a date/time string with a UTC offset in relevant places, in which case Engineer will understand that the time is in a specific zone. For example, if you specify your post’s timestamp as something like 2012-04-17 08:47:00-08:00, Engineer will understand that the time specified is 8 hours behind UTC. Generally I have found this to be a hassle, since forgetting the offset can cause incorrect post timestamps, and setting the POST_TIMEZONE is much more straightforward.

You might also find yourself in a situation where you write your posts in one timezone, but your server is in another. This generally isn’t a problem unless you’re using Emma. In that case you should be sure to set your SERVER_TIMEZONE as well.

Post Content¶

Your post content should be written in Markdown, and all the usual Markdown syntax rules apply. Engineer does provide some helpful CSS styles and template tags that might be useful when writing your posts. In addition to these, individual themes might provide their own.

Including Images¶

If you have images in your posts, you may find Engineer’s built-in img tag useful. This tag allows you to easily output consistent image markup in your posts. You must have the Jinja Post Processor Plugin enabled in order to use this tag

Theme Designer Note

The exact HTML content output by the img tag is customizable by a theme. See the Theme creation documentation for more details.

Syntax¶

The typical syntax for the img tag looks like this:

{{ img(path_to_image,
      classes=[list of CSS classes to apply],
      width,
      height,
      title,
      alt,
      link) }}

All of the arguments except the path are optional. You can also pass the image source in as a string by treating the img function as a Jinja filter. In this case, the syntax would look like this:

{{ path_to_image|img(classes=[list of CSS classes to apply],
                     width,
                     height,
                     title,
                     alt,
                     link) }}

Examples¶

Consider an img tag like this:

{{ "http://farm8.staticflickr.com/7241/7206331966_c6419e544e.jpg"|img('center', 500, 375,
    'An xkcd.com comic in Reeder', 'An xkcd.com comic in Reeder',
    link='http://www.flickr.com/photos/76037594@N06/7206331966/') }}

Using the Dark Rainbow theme, this would output the following HTML:

<div class="image caption center">
    <a href="http://www.flickr.com/photos/76037594@N06/7206331966/">
        <img src="http://farm8.staticflickr.com/7241/7206331966_66d2e5e577.jpg"
             width="500"
             height="375"
             alt="An xkcd.com comic in Reeder">
    </a>
    <p>An xkcd.com comic in Reeder</p>
</div>

Teaser Content¶

Some themes support ‘teaser content.’ As part of a post, you can specify a break in the content. Only content before the break will be displayed on list pages, such as the homepage, but individual post pages will contain the full post.

You can specify the break in your post with either -- more -- or the Octopress-style . See Post Breaks/Excerpts/Teasers for more information.

New in version 0.3.0.