Included Plugins

Engineer includes a few optional plugins you can use to further customize its behavior. If you have an idea for your own plugin, you might consider creating it yourself.

Note

Some plugin capabilities require you to explicitly give the plugin special permissions. Check the plugin’s documentation to see if this is the case. The plugin permissions system is new to Engineer 0.5.0.

Metadata Finalization

Engineer will automatically fill in pieces of metadata about your posts during the build process, and this plugin can also ‘finalize’ some of that metadata and write it back to your post file.

For example, if you have a post that you just wrote and are ready to publish, you likely want Engineer to use the current date/time as the timestamp for the post. However, in order to ensure future build processes know the right publish time for that post, the metadata needs to be in the file itself, so Engineer will automatically add timestamp: <current date/time> to your post file when it builds the site.

On the other hand, you might have a post that is in review or draft form, and you’re building the site to preview it. In that case, you don’t want the timestamp to be added to the file.

Settings

The finalization process is customizable. The FINALIZE_METADATA_CONFIG setting defines which metadata settings are finalized and what posts (based on their status) the finalization process applies to. For example, the default FINALIZE_METADATA_CONFIG looks like this:

FINALIZE_METADATA_CONFIG:
  timestamp:
    - published
  title:
    - published
    - review
    - draft
  slug:
    - published
    - review
    - draft
  url:
    - published
    - review

This metadata map tells Engineer to finalize timestamps only for published posts and normalizes titles and slugs for all posts. You can override this default map by providing your own map in your own settings file. In addition, you can turn metadata normalization on and off completely using the FINALIZE_METADATA setting.

Note

Metadata that already exists in post files will always be maintained regardless of this setting. For example, if you are using the default settings but have a draft post that already has a url value, that metadata will be maintained in the output file, even though URLs will not be set for drafts in general.

class engineer.conf.EngineerConfiguration[source]
FINALIZE_METADATA

Default: True

Turns Metadata Finalization on and off.

FINALIZE_METADATA_CONFIG

Default:

FINALIZE_METADATA_CONFIG:
  timestamp:
    - published
  title:
    - published
    - review
    - draft
  slug:
    - published
    - review
    - draft
  url:
    - published
    - review

A mapping of post metadata values to the post statuses in which they’ll be finalized. By default, Engineer will finalize timestamps only for published posts and normalizes titles and slugs for all posts.

METADATA_FORMAT

Default: 'input'

Specifies which metadata format to output. As of version 0.5.0, this only controls whether or not to force Post Metadata ‘Fencing’. When set to the default, 'input', the finalized metadata format will match that of the input.

Other valid values for this setting are:

'fenced'
Always output the metadata as fenced.
'unfenced'
Always output the metadata as unfenced.

New in version 0.4.0: In version 0.4.0, the old post normalization process has been superceded by the Metadata Finalization and Post Renamer plugins.

Changed in version 0.5.0: Added the METADATA_FORMAT setting.

Post Breaks/Excerpts/Teasers

If you wish to show only an excerpt of a post on a rollup page, you can insert a break marker into your post content and Engineer will break it up for you.

Engineer supports Octopress-style <!--more--> post breaks in addition to the simpler -- more --. Use whichever one you wish. Only the first section of the post, before the ‘more’ break marker, will be displayed on a rollup page.

By default the RSS feed that Engineer generates will only include teaser content. However, you can override this and make your feed full content by setting the FEED_FULL_CONTENT setting to true in your Engineer settings file.

The Post Breaks plugin does not need to be activated in any way; it always runs but has no effect on posts that don’t include a break marker.

New in version 0.3.0.

Changed in version 0.4.0: Added the FEED_FULL_CONTENT setting.

Post Renamer

It can be handy when your post source files have names that tell you a little about the post itself. While you can obviously name post files whatever you like, Engineer can automatically rename your files during the build process to help keep things organized. When combined with Metadata Finalization, Engineer can do a lot of heavy lifting to keep your posts organized and easy to manage.

The Post Renamer plugin is disabled by default, and can be enabled by setting the POST_RENAME_ENABLED setting to true. When enabled, the plugin uses the POST_RENAME_CONFIG setting to determine how to rename files. This configuration setting is similar in form to the PERMALINK_STYLE setting, and specifies a mapping of post status to a rename format string.

For example, the default POST_RENAME_CONFIG setting is:

POST_RENAME_CONFIG:
  draft: '({status}) {slug}.md'
  review: '({status}) {year}-{month}-{day} {slug}.md'
  published: '({status_short}) {year}-{month}-{day} {slug}.md'

With this configuration, a draft post with the title “Welcome to Engineer” would be renamed to (draft) welcome-to-engineer.md. The format strings should follow standard Python string formatting rules. The following named parameters are available for you to use in your format string:

year
The year portion of the post’s timestamp as an integer.
month
The month portion of the post’s timestamp as string - includes a leading zero if needed.
day
The day portion of the post’s timestamp as a string - includes a leading zero if needed.
i_month
The month portion of the post’s timestamp as an integer.
i_day
The day portion of the post’s timestamp as an integer.
slug
The post’s slug.
status
The post’s status as a string (e.g. draft).
status_short
The post’s status in a short form (e.g. d for draft, p for published, etc.).
timestamp
The post’s timestamp as a datetime.
post
The post object itself.

If you wish for posts of a certain status to not be renamed at all, simply use a ~ ( tilde - YAML’s equivalent to None or null) in your POST_RENAME_CONFIG setting. For example, the following setting will not rename draft and review posts, but will rename published posts according to the default configuration:

POST_RENAME_CONFIG:
  draft: ~
  review: ~

New in version 0.4.0: In version 0.4.0, the old post normalization process has been superceded by the Metadata Finalization and Post Renamer plugins.

Changed in version 0.4.2: The plugin is now disabled by default. Renaming post files caused confusion and headaches for new Engineer users.

Jinja Post Processor Plugin

This plugin runs your post content through the Jinja template engine prior to tranforming it into HTML. This allows you to use Jinja filters, variables, and other content in your posts. For example, this plugin lets you use the handy img Jinja filter to insert images into your posts consistently.

New in version 0.5.0.

Usage

The Jinja Post Processor plugin is enabled by default. If you wish to disable it, you can set the JINJA_POSTPROCESSOR_ENABLED setting to False in your configuration file. Keep in mind that disabling the plugin will cause some built-in Engineer features such as the img filter to not work.