Publ: Entry files

Last updated: 2019-05-08 7:39 AM (5 years ago)

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 follow the RFC 2822 email message format. They are, more or less, a series of lines like:

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

followed by a blank line. Long values can also be split on multiple lines by using a hanging indent:

Header-Name: Long value which continues
    on to a second line and maybe
    a third

You can define whatever headers you want for your templates, and can also have multiple headers of the same name. For example:

My-Header: foo
My-Header: bar
My-Header: baz

Header names are case-insensitive (so, for example, my-header, My-header, and My-HEADER all mean the same thing).

When using these headers from a template, they appear as part of their entry object, and can be accessed using the get mechanism.

Publ-defined headers

Publ defines a number of headers for its own use. They are as follows:

Title: The display title of the entry
Default value: None
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
- UNLISTED: A synonym for HIDDEN
- 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
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.
The path portion is URL-encoded; for example:
```
Path-Alias: /entry%20with%20spaces
Path-Alias: %28parentheses%29
```
Typically, only whitespace and percent signs must be URL-encoded.
Path-Mount: An alternate path to this entry
This is similar to Path-Alias, except that the browser will not be redirected to the canonical location; for example, if you have an entry like:
```
Title: Test
Category: blog
Entry-ID: 12345
Path-Mount: /faq
```
then both /blog/12345-test and /faq will render as the entry directly.
Also, unlike Path-Alias, if a template is specified, this will be treated as an entry template (i.e. there will be an entry object and no view object).
Path-Canonical: Specify the canonical path to this entry
Default value: /{category}/{entry id}-{slug text} (for example, /articles/general/1924-this-is-a-test)
For example, if there’s an entry with:
```
Title: Test
Category: blog
Entry-ID: 12345
Path-Alias: /faq.html
Path-Canonical: /faq
Path-Mount: /faque
```
then any access to /blog/12345-test, /blog/12345, /12345, /faq.html, etc. will be redirected to /faq. However, Path-Mount paths (/faque in the above example) will still be a non-redirecting alias.
As with Path-Mount, if a template is specified then this will be treated as an entry template.
If you specify more than one Path-Canonical header, all but one of them will be treated as Path-Mount instead; it is undefined as to which one becomes the canonical path.
UUID: A globally-unique identifier for the entry
While Publ doesn’t use this internally, having this sort of generated ID is useful for Atom feeds and the like. As such, a UUID will be automatically generated if not present.
It is highly recommended (but not technically required) that this be unique to every entry, including between different websites.
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 plain-text summary/description of the entry. Markdown is supported.
Default value: The first paragraph of text in the entry body.
Auth: A list of permissions for who can and cannot see the entry.
This is a list of identities or groups, separated by spaces. Identities/groups which start with a ! means that they cannot access the entry. For example, this line:
```
Auth: friends !mailto:erik@example.com
```
means that members of friends can access the entry, but not erik@example.com (even if they are a member of friends).
This list can grow arbitrarily long, and the rightmost rule wins.
There is also a special access group, *, which just refers to anyone who is logged in; for example:
```
Auth: *
```
will be visible to anyone who is logged in, and
```
Auth: !*
```
will only be visible to anyone who is not logged in. These rules can also stack; for example:
```
Auth: * !enemies mailto:bob@example.com
```
will be visible to anyone who’s logged in except for members of the enemies group, but mailto:bob@example.com will be allowed even if they are in enemies. This is one way that you can make an entry which is open to everyone except people who have been blocked, for example.
Note that identities won’t necessarily be an email address; they are only listed as such here for illustrative purposes. For example, a Mastodon user will appear as e.g. https://plush.city/@fluffy. See the user configuration file and admin guide for more information.
Note: Only a single Auth: header is supported. If more than one is present, only one will be used, and it is undefined as to which one that is. If you want nicer formatting on long per-entry access lists, you can format it using hanging indents:
```
Title: Bob's surprise birthday party
Auth: mailto:someone@example.com
    mailto:someone-else@example.com
    friends
    !bob
```
Attach: Another entry to “attach” to this one, useful for defining arbitrary content sections or the like. This can be by file path or by entry ID.
This is to be used with the entry.attachments and entry.attached template functions, as well as the related view parameters

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 Publ-specific extensions to this.

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:

Relative to the entry file
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:

content/entries/photos/my vacation/DSC_12345.jpg
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>

HTML tags

HTML <img> tags will use their width and height attributes to determine the image rendition size. 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 available on both HTML and Markdown entries.

Linking to things

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 tags, 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.

In HTML tags, you can also force this to apply to other attributes by prefixing them with a $, which is useful for supporting various JavaScript libraries and the like. For example:

<img $data-ondemand="image.jpg{320,320}">  <!-- becomes <img data-ondemand="/path/to/image_320x320.jpg"> -->

<iframe src="other-entry.md">  <!-- becomes <iframe src="/category/1234-other-entry"> -->

<a href="@some-asset.txt">  <!-- becomes <a href="/static/some-asset.txt"> -->

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!

This also works in HTML links; for example:

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:

[link to entry 322](322) → link to entry 322
[link to `Template format.md`](Template format.md) → link to Template format.md
[link to `/faq.md`](/faq.md) → link to /faq.md
[link to `../api/view.md#order`](../api/view.md#order) → link to ../api/view.md#order

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>

As above, you can also use these in any HTML element with the src, href, or arbitrary attributes annotated with $; for example:

<iframe src="some entry.md"></iframe> <!-- by filename -->
<div $data-popup="12345#anchor"></div> <!-- by entry ID -->

Fenced code blocks

As is typical for Markdown, Publ supports fenced code blocks, with a syntax like:

```language
Text goes here
More text
More text
```

Syntax extensions

Publ allows you to add a title to a fenced code block, by putting it on the first line and prefixed with !:

```python
! example.py
def foo():
    return None
```

This will render as:

example.py

def foo():
    return None

Note: If you need the first line of code to start with a literal ! character, put a blank line before it, or prefix it with a \. For example,

```markdown
\![alt text](image.jpg "This is an image")
```

renders as:

![alt text](image.jpg "This is an image")

You can also provide template override arguments to the code block by putting parameters after the language declaration; for example:

```{code_number_links=False}
This block has had its line number links suppressed.
```

```bash{code_highlight=False}
cat << EOF
This code has had highlighting disabled.

Test 1
Test 2
EOF
```

These render as:

This block has had its line number links suppressed.

cat << EOF
This code has had highlighting disabled.

Test 1
Test 2
EOF

HTML output

The overall code block structure is:

<figure class="blockcode">
    <figcaption>
        Block caption
    </figcaption>
    <pre>
        /* code goes in here */
    </pre>
</figure>

If a language is specified, the <pre> also gets class="highlight" and a data-language attribute that is set to the language.

If code highlighting is enabled, the code is also run through Pygments.

If line number links are enabled, the <pre> gets an empty attribute of data-line-numbers.

Each line is wrapped in a <span class="line"> and a <span class="line-content">, to allow for additional CSS formatting. If both code_highlight and code_number_links are enabled, there will also be a <a class="line-number"></a> inserted before the line-content span, and the line span will have an ID that this links to. This allows for code-line permalinks:

<pre>
    <span class="line" id="xxxL1">
        <a class="line-number" href="#xxxL1"></a>
        <span class="line-content">first line</span>
    </span>
    <span class="line" id="xxxL2">
        <a class="line-number" href="#xxxL2"></a>
        <span class="line-content">second line</span>
    </span>
    <span class="line" id="xxxL3">
        <a class="line-number" href="#xxxL3"></a>
        <span class="line-content">third line</span>
    </span>
   ...
</pre>

This markup is intended to be used with CSS counters to actually add the line numbering, which allows copy-and-paste to still function correctly. For a minimal example:

.highlight {
    counter-reset: codeline;
}

.highlight .line-number::before {
    content: counter(codeline);
    display: inline-block;
    min-width: 3em;
}

For a more thorough example of how to format fancy code, look at the code block CSS file for this website.