Extensions¶
In addition to Composers, handroll has an extension system
to plug in other functionality.
Users enable extensions
by adding with_* = true
to their site
section
in the configuration file,
where *
is the name of the extension.
For example, the blog extension is named blog
,
and with_blog = true
will enable it.
Extension authors can use the base Extension
to create new extensions.
Extensions are never directly called,
but an extension can connect to one of handroll’s Signals.
-
class
handroll.extensions.base.
Extension
(config)¶ A base extension which hooks handler methods to handroll’s signals.
-
on_frontmatter_loaded
(source_file, frontmatter)¶ Handle the
frontmatter_loaded
signal.Activate this handler by setting
handle_frontmatter_loaded
toTrue
in the extension subclass.Parameters: - source_file – Absolute path of the source file
- frontmatter – Dictionary of parsed frontmatter
-
on_post_composition
(director)¶ Handle the
post_composition
signal.Activate this handler by setting
handle_post_composition
toTrue
in the extension subclass.Parameters: director – The director instance
-
on_pre_composition
(director)¶ Handle the
pre_composition
signal.Activate this handler by setting
handle_pre_composition
toTrue
in the extension subclass.Parameters: director – The director instance
-
Extension authors can include new extensions by adding to the
handroll.extensions
entry point. For example, handroll includes
the following entry point in setup.py
:
entry_points={
'handroll.extensions': [
'blog = handroll.extensions.blog:BlogExtension',
]
}
Built-in extensions¶
Blog extension¶
The blog extension allows you to automatically generate an atom feed of blog entries. It can also create an entry list for one of your pages.
Enable the blog extension by adding with_blog = True
to
the site
section of your configuration file.
Atom feed¶
The extension requires some additional information
to create a valid atom feed.
Add a blog
section to your configruation file
with the following fields:
atom_author
- The author of the blogatom_id
- A unique identifier for the atom feed. One suggestion is to use the URL of the feed itself. For example,http://www.mattlayman.com/feed.xml
.atom_title
- The title of the blogatom_url
- The URL for the feed. For example,http://www.mattlayman.com/archive.html
.
To create the atom feed, you need to specify an output path
using the atom_output
option.
The path provided is relative to the output directory.
[blog]
atom_output = feed.xml
In this example, the atom feed would be stored
in the root of the output directory
with a filename of feed.xml
.
List page¶
To create a blog list page,
add a list_template
option to your blog
section.
If you include list_template
,
then you must also include list_output
.
list_output
is a path relative to the output directory.
When the blog extension generates the list page,
the context will receive a blog_list
.
The blog_list
is an HTML fragment of list item tags.
There is one list item tag for every post.
Here is a possible sample template.
<html>
<body>
<ul>
{{ blog_list }}
</ul>
</body>
</html>
And here is some possible output.
<html>
<body>
<ul>
<li><a href="/another_post.html">Another post</a></li>
<li><a href="/a_post.html">First post!</a></li>
</ul>
</body>
</html>
For more complex formatting,
the actual blog posts are provided
in the context
as posts
.
Blog post frontmatter¶
A source file is marked as a blog post by setting blog: True
in the front matter.
The blog front matter has required and optional fields.
Required fields:
title
- The title of the postdate
- The published date of the post. The date should be in RfC 3339 format (e.g.,2015-07-15T12:00:00Z
).
Optional fields:
summary
- A summary of the post.
When a blog post is rendered,
post
is added to the context.
This post
data contains previous
and next
attributes
which point to the previous and next chronological posts.
This is useful to include links between blog post pages.
Sitemap extension¶
The sitemap extension generates a sitemap
of your site’s HTML content.
The generated file will be stored
in the root
of the output directory
as sitemap.txt
.
Enable the sitemap extension by adding with_sitemap = True
to
the site
section of your configuration file.
Open Graph extension¶
The Open Graph extension reads blog post frontmatter
and adds open_graph_metadata
to the template context.
The data can be added to the head
section of the HTML output.
Enable the Open Graph extension by adding with_open_graph = True
to the site
section of your configuration file.
The extension produces the metadata for an Open Graph article
.
As the article
type requires an image,
additional configuration is required so that an image is always available.
You must include an open_graph
section
with a default_image
.
The default_image
is a full URL
to an image file.
This default image will be used
whenever an image
is not specified
in a blog post’s frontmatter.
[open_graph]
default_image = http://www.example.com/images/og.jpg
When image
is provided
in the frontmatter,
the value produces a URL that is related to the source file.
For example,
if you have a post in your site at a path of posts/my-topic.md
and the frontmatter includes image: butterfly.jpg
,
then the included image URL would become
http://www.example.com/posts/butterfly.jpg
.
image
can also use an absolute path.
If the frontmatter sets image: /images/ladybug.jpg
,
the final URL would be http://www.example.com/images/ladybug.jpg
regardless of where the blog post is
in your site structure.
To include the metadata, add it to your template:
<html>
<head>
{{ open_graph_metadata }}
</head>
<body>
</body>
</html>
Twitter extension¶
The Twitter extension reads blog post frontmatter
and adds twitter_metadata
to the template context.
The data can be added to the head
section of the HTML output.
Enable the Twitter extension by adding with_twitter = True
to the site
section of your configuration file.
The extension produces the metadata for an Twitter summary
card.
As the summary
type requires an image,
additional configuration is required so that an image is always available.
You must include an twitter
section
with a default_image
.
The default_image
is a full URL
to an image file.
This default image will be used
whenever an image
is not specified
in a blog post’s frontmatter.
image
follows the same rules
as described for the Open Graph extension.
The Twitter extension also expects a site_username
to connect with the relevant Twitter account.
[twitter]
default_image = http://www.example.com/images/og.jpg
site_username = @mblayman
To include the metadata, add it to your template:
<html>
<head>
{{ twitter_metadata }}
</head>
<body>
</body>
</html>