Publ: Entry files

Last updated:

Overall format

Publ entries are files saved as .md or .html in your content directory. An entry consists of three parts: Headers, above-the-fold, and below-the-fold (also known as a “cut”).

Here is what an entry might look like:

Title: My first blog entry
Date: 2018/01/04 12:34PM
Category: /blog/random

Hi, this is my first blog entry. I guess I don't have a lot to say.

.....

Well, maybe a *little* more.

Headers

Headers are, more or less, a series of lines like:

Header-Name: Header-Value
Another-Header-Name: Header-Value

followed by a blank line. (At present, Publ actually uses Python’s RFC 2822 parser, so in theory you should be able to do line continuations if that’s necessary for some reason.)

You can define whatever headers you want for your templates; the following headers are what Publ itself uses:

  • Title: The display title of the entry

    If none is given, it will try to infer the title from the filename. It will probably get this wrong.

  • Sort-Title: The sorting title of the entry

    This affects the title for the purpose of sorting, but is otherwise unused. If none is given it defaults to the entry’s display title.

  • Entry-ID: The numerical ID of the entry

    This must be unique across all entries and will be automatically assigned if missing. It must also be just a number.

    Entry IDs also provide a convenient linking mechanism; this entry has ID of 322 so a link to /322 or 322 works fine regardless of where the entry gets moved to in the future.

  • Date: The publication date and time

    This can be in any format that Arrow understands. If no timezone is specified it will use the timezone indicated in config.py.

    Default value: the modification time of the entry file (which will be added to the file for later).

    If you set this to a non-date value (e.g. now) then it will be replaced with the file modification time when the file is scanned, as if the header were omitted.

  • Category: Which category to put this entry in

    Default value: the entry file’s directory

  • Status: The publish status of the entry

    Allowed values:

    • DRAFT: This entry is not visible at all
    • HIDDEN: This entry is visible when accessed directly, but will not be included in entry listings or in previous/next links
    • PUBLISHED: This entry is visible at all times
    • SCHEDULED: Until the publication date, this acts as HIDDEN; afterwards, it acts as PUBLISHED
    • GONE: The entry has been deleted and will not be coming back; attempts to access this entry will result in an HTTP 410 GONE error.
    • DELETED: A synonym for GONE

    Default value: SCHEDULED

  • Slug-Text: The human-readable part of the URL

    In some circles this is known as “SEO text.”

    Default value: the entry title; if there is no title, the entry’s filename (minus extension)

  • Redirect-To: A URL to redirect this entry to

    This is useful if you want to remove an entry and redirect to another entry, or if you want an entry to be a placeholder for some external content (e.g. when the entry was syndicated from an external source).

  • Path-Alias: An alternate path to this entry

    This is useful for providing easy-to-remember short names for an entry, and for redirecting old, non-Publ URLs to this entry. For example, if you’re migrating from a legacy site and you have a URL like http://example.com/blog/0012345.php you can set a header like:

    Path-Alias: /blog/0012345.php

    Any number of these may be added to any given URL.

    For example, this entry has a Path-Alias of /entry-format, and the template format page can be similarly reached at /template-format.

    Note: A path-alias will never override another entry at its canonical URL; however, it can potentially override any other kind of URL, including URLs for category views and non-canonical entry URLs.

    You can also optionally specify a category template to use, by writing it after the aliased path:

    Path-Alias: /blog/0012345.php archive

    which will cause the legacy URL to remap to showing this view within the category using the archive template. If you would like to just go to the category without any specific template, use index.

  • UUID: A globally-unique identifier for the entry

    While Publ doesn’t use this for itself, having this sort of generated ID is useful for Atom feeds and the like. As such, it will be automatically generated if not present.

    It is highly recommended that this be unique across all entries.

  • Entry-Type: An arbitrary string which you can use to define an entry type

    This allows you to differentiate entry types however you want; with this you can, for example, set up something similar to what WordPress and Tumblr call “page”-type content, or use this to manage entries within a navigation sidebar or a linkroll or the like.

    Note that this is intended for affecting the layout/structure of the site, and each entry only has a single type. If you set more than one, only one of them will be used (and which one is undefined). For making content that can be filtered on multiple criteria, use tags instead.

  • Entry-Template: Use the specified template instead of entry when rendering this entry

  • Last-Modified: The date to use for the last-modified time for this entry.

    Like with Date, if you set this to a non-date value (e.g. now) then it will be replaced with the file modification time when the file is scanned.

    Default value: the entry’s Date

  • Tag: Add the specified tag to the entry. To add more than one tag, use separate Tag: headers.

  • Hidden-Tag: Like Tag, but the tag will not appear in the entry’s tag list. This lets you filter an entry without making its filter criteria visible.

  • Summary: A summary/description of the entry.

    Any text in here will replace the “description” element in the OpenGraph tag.

Entry content

After the headers, you can have entry content; if the file has a .htm or .html extension it will just render directly as HTML (with internal href and src links rewritten to local files and entries), but with a .md extension it will render as Markdown.

Publ supports a number of extensions to Markdown, specifically via Misaka (which in turn uses Hoedown). The extensions are configurable; by default it is configured to resemble GitHub-flavored markdown with the addition of Kramdown-style math (which in turn works with MathJax or KaTeX).

Markdown entries can use code fences, which support syntax highlighting via Pygments; see its rather large list of syntaxes.

There are also some Publ-specific extensions for things like cuts, image renditions, and galleries.

Custom tags

  • .....: Indicates the cut from above-the-fold to below-the-fold content (must be on a line by itself)

Images

Publ extends the standard Markdown image tag (![](imageFile)) syntax with some added features for generating display-resolution-independent renditions and Lightbox galleries. The syntax is based on the standard Markdown for an image, which is:

![alt text](image-path.jpg "title text")

(where alt text and "title text" are optional), but it adds a few features:

  • Multiple images can be specified in the image list, separated by | characters; for example:

    ![](image1.jpg "title text" | image2.jpg | image3.jpg "also title text")
  • Images can be configured by adding {arguments} to the filename portion or to the alt text; for example:

    <!-- A single image being configured -->
    ![](image.jpg{width=320,height=200})
    
    <!-- Three images configured to a width of 640, with one of them further overridden -->
    ![{width=640}](image1.jpg | image2.jpg{width=320} "this one is narrower" | image3.jpg)

You can also specify the width and height as the first one or two unnamed arguments to an argument list; for example, these two invocations are equivalent:

![{320,240}](image1.jpg | image2.jpg | image3.jpg)

![{width=320,height=240}](image1.jpg | image2.jpg | image3.jpg)

For the shorthand notation, if you want to specify only height you can use None for the width, e.g.:

![{None,240}](image1.jpg | image2.jpg | image3.jpg)

For a full list of the configurations available, please see the manual entry on image renditions.

If the image path is absolute (i.e. starts with a /) it will search for the image within the content directory. Otherwise it will search in the following order:

  1. Relative to the entry file
  2. Relative to the entry category in the content directory

So, for example, if content directory is content/entries and your entry is in content/entries/photos/my vacation/vacation.md but indicates a category of photos, and you have your static directory set to content/static, an image called DSC_12345.jpg will be looked up in the following order:

  1. content/entries/photos/my vacation/DSC_12345.jpg
  2. content/entries/photos/DSC_12345.jpg

Relative paths will also be interpreted, including ../ parent directory paths.

This approach allows for greater flexibility in how you manage your images; the simple case is that the files simply live in the same directory as the entry file, and in more complex cases things work in a hopefully-intuitive manner.

Of course, external absolute URLs (e.g. http://example.com/image.jpg or //example.com/protocol-relative.gif) are still allowed, although they are more limited in what you can do with them (for example, scaling will be done client-side and cropping options will not work). Also, keep in mind that URLs that are not under your control may change without notice.

This functionality is also available for links to images; for example:

Here is [a graph I made](my-graph.png).

In this variant you can also specify the image attributes:

Here is [the same graph at smaller size](my-graph.png{320,240}), and here it is [as a JPEG](my-graph.png{format='jpg'}).

Note that these links to images do not inherit the default image arguments from the page template (this is by design). And, of course, only a single image is supported.

Image sets

To support image sets, the following options can be added to the alt text section to wrap the image(s) in a <div>:

  • div_class: Sets the class attribute on the containing <div>
  • div_style: A string or list of strings which are added to the containing <div>’s <style> element

For example, this Markdown fragment:

![{div_class="foo"}(test.jpg | test2.jpg)]

will produce the equivalent of the following HTML:

<div class="foo"><img src="test.jpg"><img src="test2.jpg"></div>

Plain HTML entries

In plain-HTML entries, width and height attributes are parsed from the <img src> tag; for example:

<img src="foo.jpg" width="320" height="200" title="Custom title">

is equivalent to:

![](foo.jpg{320,200} "Custom title")

You can also use most of the Markdown image rendition flags, for example:

<img src="foo.jpg{200,format='png'}" title="Converted to PNG at 200 pixels across">

This <img> functionality is also available on Markdown entries.

Link targets

Both Markdown and HTML entries support a number of enhancements to how link targets are handled; this allows the transparent use of local file paths in your entries.

In HTML entries, this applies to all href and src attributes (e.g. <a href="example.md">link</a> and <audio src="example.mp3" controls>).

In Markdown entries, this also applies to images (e.g. ![](example.jpg)) and hyperlinks (e.g. [example link](example.md)) in addition to applying to embedded HTML content.

Local files

Entries can link to files that are stored within the content directory, using the same relative path rules as images. For example, if you have a file term paper.pdf in the same directory as my entry.md, then from the entry you can link to it with:

You want to read [my paper](term paper.pdf)? Well here you go!

Similarly, from an HTML entry, this will work:

You want to read <a href="term paper.pdf">my paper</a>? I'm flattered!

Any file type is supported; however, keep in mind that an HTML or Markdown file will be interpreted as an entry. If you would like to serve one up as just their plain content, you can give it headers like:

Status: HIDDEN
Entry-Template: _plain

and create a templates/_plain.html file that is simply:

{{entry.body}}
{% if entry.more %}
.....
{{entry.more}}
{% endif %}

Static assets

Starting a link target with @ acts as a shorthand for linking to a file in the static assets directory. For example,

[here is a file](@files/file.txt)

will link to the file files/file.txt within the static files for the site. This is more portable than linking to the static files directly, e.g. /static/files/file.txt.

This also applies to images (e.g. ![](@foo.jpg) will display the image /static/foo.jpg), although it will be treated the same way as an external image; if you want the image to be scaled to save bandwidth, it is better to put it into your content tree instead.

When writing HTML, the following is equivalent to the above two examples:

<a href="@files/file.txt">here is a file</a>
<img src="@foo.jpg">

Entries

You can also link to an entry by its entry ID or by an absolute or relative file path to the source file. This also supports anchors (#). Some examples:

And the HTML equivalents to the above:

<a href="322">link to entry 322</a>
<a href="Template format.md">Link to <code>Template format.md</code></a>
<a href="/faq.md">Link to <code>/faq.md</code></a>
<a href="../api/view.md#order">Link to <code>../api/view.md#order</code></a>