The authentication file, normally stored in users.cfg unless configured differently, stores a set of permissions groups for different authenticated users.
The format is pretty simple:
[admin] http://example.com/ mailto:me@example.com [friends] mailto:someone@example.com mailto:someone-else@example.com http://example.com/~friend/ good-friends [enemies] mailto:mark@facebook.com http://tumblr.com/ [good-friends] https://beesbuzz.biz/
Simply put, each group is indicated by [group_name], and each line after the group name indicates the authenticated identities (and other groups) which are a part of that group. So, in this case, anyone who is in the good-friends group will also be in the friends group. All identities are given as full URIs.
Identities can also be used as a group name, to help manage those folks who have more than one identity that you want to treat equivalently; for example:
[https://beesbuzz.biz] mailto:fluffy@beesbuzz.biz ; Twitter URLs are given in /i/user/NNNNN format; this allows things to keep ; working if a user changes their username, and prevents others from hijacking ; their identity as well. https://twitter.com/i/user/993171 https://plush.city/@fluffy
This will give the identities mailto:fluffy@beesbuzz.biz, https://twitter.com/i/user/993171, and https://plush.city/@fluffy membership in all groups that https://beesbuzz.biz is in as well. However, the opposite is not true; https://beesbuzz.biz won’t automatically have access to entries that are only allowed for https://plush.city/@fluffy, for example.
Any identities which belong to the administrative group (which is admin by default but can configured differently) will have access to all entries, as well as the administrative dashboard. Otherwise, users are subject to the permissions system.
You can also start a line with # or ; to indicate that it is a comment.
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 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 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
ATTACHMENT: Similar to HIDDEN, except it will also be included in an entry’s attachment list
ATTACH: A synonym for ATTACHMENT
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.
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
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.
.....: Indicates the cut from above-the-fold to below-the-fold content (must be on a line by itself)Publ extends the standard Markdown image tag () 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:
(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 -->  <!-- 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:
 
For the shorthand notation, if you want to specify only height you can use None for the width, e.g.:
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:
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.jpgcontent/entries/photos/DSC_12345.jpgRelative 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.
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> elementFor example, this Markdown fragment:
will produce the equivalent of the following HTML:
<div class="foo"><img src="test.jpg"><img src="test2.jpg"></div>
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:
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.
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. ) 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"> -->
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 -%}
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.  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">
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#orderAnd 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 -->
As is typical for Markdown, Publ supports fenced code blocks, with a syntax like:
```language Text goes here More text More text ```
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:
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 \ ```
renders as:
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
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.
]]>