The user object provides the following:

• identity: The identity URL of the user

• humanize: A humanized version of the identity URL

• name: The display name of the user

• profile: The user profile; see the Authl documentation for the relevant keys.

  Note that this will not necessarily be available, depending on how and when the user logged in. For example, if the database has been fully reset (due to e.g. a Publ upgrade or a server migration) since they last logged in, or if the user logged in from a different instance on a load-balanced configuration using a per-instance database, the profile will likely not be present.

• groups: A list of the groups they belong to (not including the user’s identity group)

• auth_groups: The full list of matching authentication groups (including the user’s own identity group)

• is_admin: True if the user is a member of the administrative group

• auth_type: How the user’s authentication was obtained; possible values:

  • 'session': Normal login flow/session cookie
  • 'token': Bearer token

• scope: The user’s permission scopes, if applicable (typically if the login was via a bearer token)

• last_login: The last time the user logged in

  This may not be available, per the same rules as user.profile

• last_seen: The last time the user was active on the site

• is_bot: Whether the page is currently being viewed by a declared bot

• token(lifetime,scope=None): A function to generate an HTTP Bearer token for preauthorization.

  Arguments:

  • lifetime: How long the token is good for, in seconds
  • scope: The access scopes that should be associated with the token

  See using bearer tokens for more information.

For the most part you should only use user.name to address the user, and possibly use user.groups to check for particular group membership if that is something you want to show them. For example, if you use user groups as a means of managing memberships or rewards or the like, you could do something like:

Hello, {{user.name}}.
{% if 'current_members' in user.groups %}
    Your membership is current!
{% else %}
    You aren't currently a member. Please consider <a href="/subscribe">becoming one</a>.
{% endif %}

When extending Publ using additional Python functions, the current user can be retrieved with:

import publ.user
user = publ.user.get_active()

In all contexts you can check the truthiness of the user object to see if someone is logged in; bots do not count as logged-in users. For example, in a template:

{% if user %}
    <p>Hello user {{user.name}}!</p>
{% elif user.is_bot %}
    <p>Hello bot {{user.name}}!</p>
{% else %}
    <P>Howdy, stranger!</p>
{% endif %}

The template object provides the following:

• name: The name of the template
• filename: The underlying filename of the template
• last_modified: When the file was most recently modified
• image: Resolves an image relative to this template’s context, by path. This is a context-specific version of the global image function.

The view object has the following things on it:

• entries: A list of all of the entries that are visible and authorized in this view

  Optionally takes a parameter, unauthorized, which indicates the maximum number of unauthorized entries which will be included. If this is a number, that number of unauthorized entries will be included; if True, all unauthorized entries will be included. These entries will count against the count limit, if any. Defaults to 0.

  Iterating on the view itself is equivalent to iterating on its entries without any arguments.

• deleted: A list of all of the entries that were deleted from this view (with Status: GONE or Status: DELETED)

• unauthorized: A list of entries which would be included if the user were authorized.

  This is mostly so that a template can indicate whether a logged-out user should try logging in to see the protected entries, or for feeds to show placeholders.

  Optionally takes a parameter, count, which indicates the maximum number that will be included. If not specified it will use the count limit, if any.

  Note that visible, authorized entries do not count against the limit.

• has_unauthorized: Indicates whether the view has any entries which could become visible if a different user were logged in.

• count: The number of visible entries in the view

• last_modified: A last-modified time for this view (useful for feeds)

• spec: The view’s specification (category, count, date, etc.)

  This is in the form of the arguments that would be passed to get_view to obtain this view. For example, you can use 'date' in view.spec to determine whether a view is date-based.

• previous: The previous page for this view, based on the current sort order

• next: The next page for this view, based on the current sort order

• older: The previous page for this view, going back in time

• newer: The next page for this view, going forward in time

• current: The current/default page of this view; can take additional restriction parameters

• is_current: Whether this view is the current/default page

• paging: Returns the type of pagination that is in effect for this view; one of:

  • offset: Based on entry offset
  • year: Based on the entry’s publication year
  • month: Based on the entry’s publication month
  • day: Based on the entry’s publication day

  These values are the same as the paging parameter of entry.archive.

• pages: A list of every page for this view based on the current pagination.

  Note: This will probably be very slow; use sparingly.

• link: The link to this view; optionally takes the following arguments:

  • category: Which category to use (defaults to the category this view is queried against)
  • template: Which template to use (defaults to the index template)
  • absolute: Whether the URL should be absolute or relative
    • False: Use a relative URL (default)
    • True: Use an absolute URL

• first: The first entry in the view

• last: The last entry in the view

• newest: The newest entry in the view

• oldest: The oldest entry in the view

• range: A textual description of the range of entries on this view, if the view has any sort of pagination-type constraints. Takes the following optional arguments:

  • day: The format to use for daily pagination, or a time period within a month; defaults to YYYY/MM/DD
  • week: The format to use for a weekly pagination; defaults to YYYY/MM/DD
  • month: The format to use for a monthly pagination, or a time period covering multiple months; defaults to YYYY/MM
  • year: The format to use for a yearly pagination, or a tim eperiod covering multiple years; defaults to YYYY/MM
  • span: The format to use for a range of entries where the first and last entry dates differ (after formatting); defaults to {oldest} — {newest} ({count})
  • single: The format to use for a range of entries where the first and last are within the same time period; defaults to {oldest} ({count})

  If there is only a single entry in the view, the range property will be formatted for its time period directly, and it only uses the day, month, or year format.

  If there are multiple entries, then the time period is chosen with the following logic:

  • If they are within the same month, it uses day
  • If they are within the same year (but on different months), it uses month
  • Otherwise, it uses year

  Both dates are formatted based on the format corresponding to the chosen period. If they are the same, the single format is used; otherwise the span format is used. Both of these formats receive the following template values:

  • oldest: The formatted date of the earliest entry
  • newest: The formatted date of the latest entry
  • count: The number of entries in the view

  The specified formats for day month and year can be as specific as you would like; for example, if you want to always show the months in question regardless of the span, you can set all three formats to YYYY-MM, or on the other end of the spectrum you could indicate the full format down to the nanosecond if you really want to for some reason.

  Any format string accepted by Arrow is acceptable (for example, MMMM YYYY will appear as January 2012).

• tags: Any tags that are applied to this view, provided as a (possibly-empty) list.

• tag_add: Generates a view with one or more tags added

• tag_remove: Generates a view with one or more tags removed

• tag_toggle: Generates a view with one or more tags toggled

  This is useful for a tag browser where you want to be able to toggle tags on and off; for example:

  <ul>
  {% for name,count in category.tags %}
  <li><a href="{{view.tag_toggle(name)}}">{{name}}</a> ({{count}} entries)</li>
  {% endfor %}
  </ul>
  

Getting subviews

Any view object can also take arguments to further refine the view; the following arguments are supported:

• category: The top-level categories to consider; can be a single category or a list of categories.

  Setting this to None will get entries from all categories; this is equivalent to category='',recurse=True

• category_not: Categories to exclude; this can be either a single category, or a list of categories.

• recurse: Whether to include subcategories.

  • True: Include subcategories
  • False: Do not include subcategories (default)

• future: Whether to include entries from the future.

  • True: Include future entries
  • False: Do not include future entries (default)

• date: Limit to entries based on a specified date; this can be of the format YYYY, YYYY-MM, or YYYY-MM-DD.

• count: Limit to a maximum number of entries.

  If date is set, count has no effect.

• entry_type: Limit to entries with a specific Entry-Type header

• entry_type_not: Limit to entries which do NOT match a specific entry type

  These can be a single string, or it can be an array of strings. Note that these are case-sensitive (i.e. "PaGe" and "pAgE" are two different types).

  • get_view(entry_type='page'): only get entries of type “page”
  • get_view(entry_type_not='page'): only get entries which AREN’T of type “page”
  • get_view(entry_type=['news','comic']): get entries which are of type ‘news’ or ‘comic’
  • get_view(entry_type_not=['news','comic']): get entries of all types except ‘news’ or ‘comic’

  Mixing entry_type and entry_type_not results in undefined behavior, not that it makes any sense to do that anyway.

• tag: Limit the view to entries which match the listed tag(s).

• tag_filter: What filter criterion to use for matching tags. One of:

  • 'ANY': All entries which have at least one of the listed tags (default); this can also be spelled 'OR'
  • 'ALL': Entries which have all of the listed tags; this can also be spelled 'AND'
  • 'NONE': Entries which have none of the listed tags'; this can also be spelled 'NOT'

• start: Limit the view to start with this entry, regardless of sort order

• last: Limit the view such to none newer than the specified entry (by id or object)

• first: Limit the view such to none older than the specified entry

• before: Limit the view to only entries which came before the specified entry

• after: Limit the view to only entries which came after the specified entry

• order: What sort order to provide the entries in; one of:

  • oldest: Oldest-first
  • newest: Newest-first (default)
  • title: Sorted alphabetically by title

• has_attachments: Limit the view to entries with (if True) or without (if False) attachments

• is_attached: Limit the view to entries which are (if True) or are not (if False) attachments

• attachments: Limit the view to entries which are attachments of the specified entry

• attached: Limit the view to entries which have the specified entry attached

For example, this will print the titles of the first 10 entries in the view, including subcategories:

{% for entry in view(count=10,recurse=True) %}
    {{entry.title}}
{% endfor %}

If you want to use the same view refinement multiple times, you can use {% set %}:

{% set content = view(count=10,recurse=True,entry_type_not='sidebar') %}
{% if content.entries %}
<ul>
{% for entry in content.entries %}
<li>{{entry.title}}</li>
{% endfor %}
</ul>
{% endif %}

view(...) vs get_view(...)

The global get_view() function creates an entirely new view from scratch, rather than basing it on the current default view. Some possible uses for this are:

• Getting a link to the latest entry on the entire site (e.g. get_view().newest)

• Properly showing the current category’s sidebar links without filtering them by date or page (e.g. get_view(category=category,entry_type='sidebar'))

  Note that this can also be achieved with view.current(entry_type='sidebar')

• Having a global set of sidebar links (e.g. get_view(entry_type='sidebar'))

The category object provides the following:

• path: The full path to the category

• basename: Just the last part of the category path

• name: A display name for the category.

  This defaults to taking the category basename, converting _s to spaces, and then title-casing the name. For example, the category some/long/category_name will have a default name of "Category Name". This can be overridden using a meta file.

  Optionally takes HTML processing arguments.

• subcats: The subcategories of this category. Takes the following argument:

  • recurse: Whether to include the subcategories of the subcategories, and their subcategories and so on. Possible values:

    • False: Only include direct subcategories (default)
    • True: Include all subcategories

• parent: The parent category, if any

• link: The link to the category; optionally takes the following arguments:

  • template: Which template to use when rendering the category
  • absolute: Whether to format this as an absolute or relative URL
    • False: Use a relative link (default)
    • True: Use an absolute link

• first: Returns the first entry in this category; optionally takes view arguments

• last: Returns the last entry in this category; optionally takes view arguments

  Note that first and last will potentially point to entries for which the user is not authorized. If that matters, use get_view instead.

• get: Get a header defined in the meta file

• get_all: Get all instances of a meta file header as a list

• description: Get the category description from the meta file, if it exists. This optionally takes the standard HTML processing arguments.

• sort_name: The name used for sorting

• breadcrumb: A list of the categories that lead to this one, as category objects, including the current one.

• root: The root category of the blog, useful for storing site-level metadata (such as the site name or global configuration).

  This is roughly equivalent to category.breadcrumb[0], but is slightly more efficient and easier to type.

• tags: A list of tags available on the category, provided as pairs of name and count.

  This can take optional view arguments, such as recurse, tag, and tag_filter.

  There are multiple ways to access the tag information, depending on preference; for example, you can separate them in the loop:

  <ul>
  {% for name,count in category.tags %}
  <li><a href="{{view(tag=name)}}">{{name}}</a> ({{count}} entries)</a></li>
  {% endfor %}
  </ul>
  

  or you can get at them directly:

  <ul>
  {% for tag in category.tags %}
  <li><a href="{{view(tag=tag.name)}}">{{name}}</a> ({{tag.count}} entries)</a></li>
  {% endfor %}
  </ul>
  

  This does not provide any built-in sorting; you can use Jinja’s sort filter for that:

  <ul>
  {% for name,count in category.tags|sort(attribute='count',reverse=True) %}
  <li><a href="{{view(tag=name)}}">{{name}}</a> ({{count}} entries)</a></li>
  {% endfor %}
  </ul>
  

  If you want the tags to display based on a view you can pass in **view.spec as the argument list; for example, this snippet will override the page’s view to require all tags to be present, and print a refinement list of tags:

  {% set view = view(tag_filter='ALL') %}  {# modify view to require all
                                              selected tags to be present #}
  
  <ul>
      {% for name,count in category.tags(**view.spec) %}
      <li><a href="{{view.tag_toggle(name)}}">{{name}}</a> ({{count}})</li>
      {% endfor %}
  </ul>
  

  }

• image: Resolves an image relative to this category’s context, by path. This is a context-specific version of the global image function.

• The following properties are also available but probably aren’t of use to template authors, and are only listed for the sake of completion. You should not rely on them for anything as they might change without warning.

  • file_path: The file path of the category’s metadata file

  • aliases: The various registered path aliases for this category

Example template code for printing out an entire directory structure (flattened):

<ul>
{% for subcat in category.subcats(recurse=True) %}
<li>{{subcat.path}}: {{subcat.name}}</li>
{% endfor %}
</ul>

Example template code for printing out the directory structure in a nice recursive manner:

<ul>
{% for subcat in category.subcats recursive %}
    <li>{{ subcat.basename }}: {{ subcat.name }}
    {% if subcat.subcats %}
    <ul>{{ loop(subcat.subcats)}}</ul>
    {% endif %}</li>
{% endfor %}
</ul>

Categories can also be compared to other categories, which is useful for determining if a subcategory is the same as this one. This snippet will show all of the categories on the website, with the currently-visible one getting a class of here and any parent categories getting a class of parent:

<ul>
{% for subcat in category.root.subcats(recurse=True) %}
{% if subcat == category %}
<li class="here">{{category.path}}</li>
{% elseif subcat in category.breadcrumb %}
<li class="parent"><a href="{{category.link}}">{{category.path}}</a></li>
{% else %}
<li><a href="{{category.link}}">{{category.path}}</li>
{% endif %}
{% endfor %}
</ul>

Meta files

Category data can be added using a metadata file, which is simply a file whose name ends in .cat or .meta and lives somewhere in the content directory. Similarly to entry files, this will default to using its place in the content directory for the category to use, but this can also be overridden using a Category: header.

The headers supported by Publ itself:

• Category: Specifies which category this file refers to
• Name: Overrides the friendly/display name of the category (i.e. category.name)
• Index-Template: Use this template instead of index when rendering this category (useful if you want to override a category or site’s index template without overriding its subcategories)
• Entry-Template: Use this template instead of entry when rendering an entry
• Sort-Name: The name to use when sorting this in a subcategory list
• Path-Alias: Redirects an unused path to this category; can optionally take a template parameter
• Path-Mount: Display an otherwise-unused path as if it’s a view of this category; can optionally take a template parameter

For example, given the file some/category/info.cat:

Name: Random Category

it will set the name attribute of the some/category category to "Random Category". However, if the file contains:

Name: Specific Category
Category: other/category

then it will set the name attribute of the other/category category to "Specific Category".

Similarly to entries, this also supports the Path-Alias and Path-Mount headers; for example:

Category: /art/sketchbook
Path-Alias: /comics/cat-sketchbook.php archive
Path-Mount: /sketchbook

will redirect requests to /comics/cat-sketchbook.php to the /art/sketchbook category using the archive template (i.e. a path like /art/sketchbook/archive), and requests to /sketchbook will render this category using the default template (without redirecting).

You can also define any other arbitrary values you like, which will then be put on the category object, and which are accessible directly via get and get_all. The behavior is the same as on entry files.

Any text after the headers will be treated as the description for the category. Markdown is supported.

Note that at least one header is required. If you just want to provide a description and no other configuration, you can simply start the file with a blank line, or you can use a bogus header, for example:

Asdf: qwer

Here is a description with no real configuration.

If you want to change the order of subcategories in a subcategory list, that is easy to do with the Sort-Name property; for example, if you have categories named foo, bar, and baz which you want to appear in that order, you can do something like:

Sort-Name: 1-foo

Sort-Name: 2-bar

Sort-Name: 3-baz

in their respective categories.

Default properties

The entry object has the following methods/properties:

• id: The numerical entry ID

• title: The title of the entry

  This property can be used directly, or it can take HTML processing arguments, as well as the following:

  • always_show: Whether to always show the title, even if the entry isn’t authorized; use with caution. (default: False)

• summary: The entry’s summary text

  This property can be used directly, or it can take HTML processing arguments, as well as the following:

  • always_show: Whether to always show the summary text, even if the entry isn’t authorized; use with caution. (default: False)

• entry_type: The value of the entry’s Entry-Type header, if any.

• private: Indicates whether this entry is only visible to logged-in users.

• authorized: Indicates whether this entry is visible to the current user.

• body, more, and footnotes: The different content sections of an entry.

  body is the section above the fold.

  more is the section below the fold.

  footnotes are the footnotes for the entire entry.

  These properties can be used directly, or they can take any of the following parameters:

  • The standard HTML processing arguments

  • footnotes_link: Specifies the base URL for footnote links; defaults to the entry’s URL.

    From body and more this refers to the URL the footnotes will display on.

    From footnotes this refers to a URL where the entry text will be visible.

    You can make these different if you want to do something fancy like keeping your footnotes on a separate page (using an archive template or the like); for example, {{entry.more(footnotes_link=entry.link(template='footnotes'))}}

  • footnotes_class: Specifies the CSS class for the <sup> that contains the footnote reference link. Defaults to none.

    If you would like to style the <a> element, you can use CSS selectors [rel="footnote"] and [rev="footnote"] for the reference and return links, respectively.

  • footnotes_return: Specifies the text to put inside the return link; defaults to '↩'.

  • toc_link: The base URL for the heading’s anchor link (for use from table of contents or generic permalinks); defaults to the entry’s URL.

  • heading_link_class: The HTML class attribute to add to the self-link from within headings; defaults to none.

    This is useful for e.g. displaying a fancy permalink marker; for example, you can render the entry with:

    {{ entry.more(heading_link_class='toc')}}
    

    and use a stylesheet rule like e.g.

    .toc:before {
        position: absolute;
        margin-left: -1ex;
        content: '#';
        color: #777;
    }
    

  • heading_link_config: Additional attributes to add to the self-link from within headings (for e.g. title or data-* or the like); defaults to nothing.

  • heading_template: A template string for how to format headings; takes the following format fragments:

    • link: The open link tag (e.g. <a href="entry#anchor" class="linkClass">)
    • text: The formatted text of the heading itself

    This defaults to {link}</a>{text} (the <a> is contained within {link}).

    Note that this template will always be rendered inside the heading tags (e.g. <h2 id="foo"><a class="toc" href="entry#foo"></a>Foo</h2>).

    If you would not like any self-link to be produced for some reason, set heading_template to {text}.

  • code_highlight: Whether to apply syntax highlighting to code blocks with a declared language (default: True)

  • code_number_links: Whether to generate line-numbering links within code blocks; see the fenced code extensions for more information. (default: True)

    Set this to a string value to override the base URL for the line number links.

• toc: The table of contents for an entry.

  Renders a table of contents based on the headings of the entry; only applies to Markdown entries.

  In addition to the standard HTML processing arguments, it takes the following arguments:

  • toc_link: The base URL for links to the entry; defaults to the entry’s link.

  • max_depth: How many levels deep to render

• card: <meta> tags for an OpenGraph card

  Like body and more, this takes arguments that affect the image renditions; you will almost certainly want to set width, height, and count.

  This will generate an appropriate og:title, og:url, og:image, and og:description tags based on the entry’s permalink and text. og:description contains the entry summary, and there will be og:image tags for up to the first count images.

  If you use this, your template should also provide your own og:type tag, e.g.

  {{ entry.card(width=640,height=350,resize="fill") }}
  <meta property="og:type" content="website" />
  

  Please see the OpenGraph documentation for more information.

  This also accepts the markdown_extensions argument, as well as the following additional arguments:

  • image: A path or URL to an image that should be used as the card image; this can be used to provide a custom property or fallback logic in your template, such as:

    {{ entry.card(width=640,height=640,image=entry.get('card-image'), image_fallback='default-card.png') }}
    

    • None indicates that it should use the first image found in the entry itself (the default) or the value of image_fallback if there’s no image in the entry body
    • False indicates that there should be no image at all

  • image_fallback: A path or URL to an image to use if there’s no image specified in the entry

• category: The category that this entry belongs to; this is provided as a category object.

• date: The publication date and time of the entry, as an Arrow object.

  This is taken from the entry’s Date header.

  Since it’s an Arrow object you can use it directly to get an incredibly precise time, but you’ll probably want to call a method on it such as format() or humanize().

• date_year, date_month, date_day: Three pre-defined formats of date for the purpose of making it easier to use Jinja’s groupby functionality.

  For example, this snippet will collate the visible entries by month:

  <ul>{% for month,entries in view.entries|groupby('date_month') %}
      <li>{{month}}
          <ul>{% for entry in entries %}
          <li>{{entry.date.format()}}: <a href="{{entry.link}}">{{entry.title}}</a></li>
          {% endfor %}</ul>
      </li>
  {% endfor %}</ul>
  

• permalink: A permanent link to the entry

  Takes the following arguments:

  • absolute: Whether to format this as an absolute or relative URL
    • False: Use a relative link (default)
    • True: Use an absolute link
  • expand: Whether to expand the URL to include the category and slug text
    • False: Use a condensed link
    • True: Expand the link to the full entry path (default)

  Whether to use an expanded link or not depends on how “permanent” you want your permalink to be; a condensed link will always cause a redirect to the current canonical URL, but an expanded link may go obsolete and still cause a redirection. The expanded link is generally better for SEO, however, and thus it is the default even if it isn’t truly “permanent.” (But then again, what is permanent, anyway?)

• link: A destination link to the entry

  This is the same as permalink except it will also follow an entry’s Redirect-To destination.

• tags: A list of tags associated with this entry.

• archive: Get an archive link for rendering this in a category view.

  This takes the following arguments:

  • paging: The pagination type; one of:
    • "day": Entries for that day
    • "month": Entries for that month
    • "year": Entries for that year
    • "week": Entries for that week
    • "offset": Goes to the page starting with this entry (default)
  • template: Which template to use for the link (defaults to '', i.e. the default/index category template)
  • category: Which category to link to; defaults to the entry’s own category
  • absolute: Whether to use an absolute link (defaults to False)
  • tag: Limit the view to the specified tag(s)

• last_modified: A last-modified time for this entry.

  This is taken from the entry’s Last-Modified header.

• next: The next entry (ordered by date)

  This can also take the same arguments as get_view(), with the following differences:

  • count has no effect
  • If category is unspecified, it defaults to the entry’s category

  Examples:

  <!-- link to the next entry in its category -->
  {% if entry.next %}
  <a href="{{ entry.next.link }}">{{ entry.next.title }}</a>
  {% endif %}
  
  <!-- link to the next entry in the entire 'comics' section where the type isn't 'news' or 'recap' -->
  {% set next_comic = entry.next(category='comics',entry_type_not=['news','recap']) %}
  {% if next_comic %}
  <a href="{{ next_comic.link }}">{{ next_comic.title }}</a>
  {% endif %}
  

• previous: The previous entry (ordered by date)

  This takes the same arguments as next.

• get: Get a header from the entry file

  This takes the following arguments:

  • name: The name of the header to retrieve
  • always_allow: Whether to always retrieve it, even if the entry is unauthorized (default: False)

  Note that if there’s more than one of a header, it’s undefined which one this will retrieve. If you want to get more than one, use get_all instead.

  Header names are not case-sensitive (i.e. 'fooBar', 'Foobar', and 'FOOBAR' are all equivalent).

  Note that this will get the raw header values, rather than anything interpreted by Publ. So, for example, entry.get('date') will return the Date: header string, rather than the display date of the entry.

  See the section on header retrieval for more information.

• get_all: Get all of a header type from an entry, as a list.

  This takes the following arguments:

  • name: The name of the header to retrieve
  • always_allow: Whether to always retrieve it, even if the entry is unauthorized (default: False)

  For example, this template fragment will print out all of the Author headers in an unordered list, but only if there are any Author headers:

  {% if entry.Author %}{# equivalent to entry.get('Author') #}
  <ul class="authors">
      {% for author in entry.get_all('Author') %}
      <li>{{ author }}</li>
      {% endfor %}
  </ul>
  {% endif %}
  

  Header names are not case-sensitive (i.e. 'fooBar', 'Foobar', and 'FOOBAR' are all equivalent).

  Note that this will get the raw header values, rather than anything interpreted by Publ. So, for example, entry.get_all('category') will retrieve the raw text of the Category: header, rather than the entry’s category object.

• attachments: Other entries which are attached to this one, using the Attach: header.

  This takes the standard view arguments. Note that the default ordering is undefined, and if order matters you should specify it. For example:

  {% for attachment in entry.attachments(order='oldest') %}
  

  will order by date, and

  {% for attachment in entry.attachments(order='title') %}
  

  will order them by title (honoring the Sort-Title attribute). You can also sort by arbitrary metadata headers; for example:

  {% for attachment in entry.attachments|sort(attribute='My-Custom-Header')} %}
  

• attached: Like attachments, but it shows the entries that this entry is attached to.

• image: Resolves an image relative to this entry, by path. This is a context-specific version of the global image function.

• The following properties are also available but probably aren’t of use to template authors, and are only listed for the sake of completion. You should not rely on them for anything as they might change without warning.

  • file_path: The file path of the entry’s content file

  • status: The publish status of the entry

    Note that as of Publ 0.3.14 this is a numerical value; in future versions this may change to a string or internal data representation. You should not actually rely on this for anything public.

  • slug_text: The URL slug text for the entry

  • redirect_url: The value of the Redirect-To header, if any

  • sort_title: The value of the Sort-Title header, if any

  • entry_template: The value of the Entry-Template header, if any

  • display_date, utc_date, local_date: Various forms of the entry’s date used for internal purposes

  • aliases: The various registered path aliases for this entry. A list of items, each providing the following properties:

    • path: The incoming path
    • url
    • entry
    • category
    • template

Header retrieval

If you have defined custom headers, you can do several different things with them:

• You can always use entry.get('header-name'), or entry['header-name'] which is equivalent. If there are multiple headers of the same name, it is undefined which one this will get.

• entry.get_all('header-name') will get all of the raw values of a header, as an array. For example, with an entry like:

  Title: My weird day
  Noun: first noun
  Noun: second noun
  Noun: third noun
  

  then entry.get_all('noun') will return an array like ['first noun', 'second noun', 'third noun'] (although the order isn’t guaranteed).

• If the header name is a valid variable name (i.e. starts with a letter or underscore, and only contains letters, numbers, and underscores), and doesn’t conflict with one of the built-in properties, you can also get it using the . operator; for example, in an entry like:

  Title: This is a test
  Verb: embiggen
  

  entry.verb will be 'embiggen'.

  However, there’s always the possibility that a future Publ update might end up using your custom header name as a built-in property, so you can’t be 100% sure that this will continue to work forever.

• The in keyword will let you know if a header exists on an entry; for example, this template fragment:

  <h1>{{entry.title}}</h1>
  {{entry.body}}
  
  {% if 'cut' in entry %}
  <details class="cut"><summary>{{entry.cut}}</summary>
  {{entry.more}}
  </details>
  {% endif %}
  

  lets you make an entry like this:

  Title: An entry with a cut
  Cut: Extreme nerdery
  
  Want to hear a secret?
  
  .....
  
  I'm a gigantic nerd.
  

  which will render like:

  <h1>An entry with a cut</h1>
  
  <p>Want to hear a secret?</p>
  
  <details class="cut"><summary>Extreme nerdery</summary>
  <p>I'm a gigantic nerd.</p>
  </details>
  

  Note that this is generally the same as simply doing e.g.

  {% if entry.cut %}
  

  but it’s slightly more efficient and also can simplify some template logic, probably.

• If the header name is a valid variable name (i.e. consists of only letters, numbers, and underscores, and starts with a letter or underscore), and doesn’t conflict with an API function, you can also retrieve it directly, e.g. entry.Foobar is equivalent to entry.get('Foobar'). It is recommended that if you do this, always start the name with a capital letter, to avoid conflicts with any future API functions (e.g. entry.Next will always be equivalent to entry.get('Next')).

  You can also check to see if the entry has a header