Output Location

Learn how input locations are translated to output locations in Qgoda.

Please note that determining the output location for assets differs significantly from other systems for example Jekyll. Whereas in Jekyll you normally set the permalink of an asset, in Qgoda you normally set the output path and the permalink is computed from the path. The result is very similar but maybe more flexible.

By default, an asset's location is simply preserved. That means if you have an asset {srcdir}/assets/images/logo.jpeg it will be copied to {sitedir}/assets/images/logo.jpeg.

Path Translation

Processed assets are subject to path translation. Their relative path to the site directory is by default modified. With the default configuration the asset {srcdir}/pages/en/about-qgoda.htm would end up as {sitedir}/pages/en/about-qgoda/index.htm and the markdown input file {srcdir}/posts/en/version-0.2-released.md would end up as {sitedir}/posts/en/version-0.2-released/index.html.

For the gory details of the process, let's take the input location {srcdir}/posts/en/version-0.2-released.md as an example.

The starting point is the relative path to the source directory /posts/en/version-0.2-released.md which has the following components:

posts/en
The directory portion.
version-0.2-released
The basename, that is the filename portion without the suffix or suffixes.
md
The suffix or filename extension.

By default the output location of a document in Qgoda relative to the configured site directory is {directory}/{basename}/{index}.{suffix}. The variable index has the default value index which is no coincidence but the default value used by all common web servers.

Suffix Translation

Asset processing is triggered by the suffixes of the source file. The triggers are defined in the variable processors.triggers in the site configuration file _config.yaml. Look at this excerpt of the Qgoda default configuration:

processors:
    triggers:
        md: markdown
        html: html
        htm: html
    chains:
        markdown:
            modules: [Markdown, HTML]
            suffix: html
            wrapper: html
        html:
            modules: HTML
   modules:
       Markdown: Markdown
       HTML: Template::Toolkit

The suffix md triggers the processor chain markdown. This chain has configured an output suffix html. The translated filename of the output file is therefore not index.md but index.html.

The processor chain html does not define an output suffix. The suffix is therefore left untouched.

Multiple Suffixes

A filename can have multiple suffixes, for example what-is-qgoda.md.utf8.fr. This is useful for content negotiation as implemented in the popular Apache web server. When doing suffix translation, Qgoda translates the rightmost suffix. The example filename would therefore be translated into what-is-qgoda/index.md.utf8.fr.

It is also important to note that all suffixes are considered for processor chain selection. The rightmost suffix wins. If you have a filename example.html.md the markdown processor chain will be selected because md is right of html.

Gory Details of Suffix Parsing

You may have noticed in one the above example the filename version-0.2-released.md which gets translated into version-0.2-released/index.md. Obviously only md is considered a suffix and 2-released is not.

Qgoda's notion of a suffix is a string of one or more alphanumerical characters. Since 2-released contains a hyphen, it is not considered a suffix.

Suffixes are extracted right to left, stopping at the first false positive. Take version-0.22.beta-released.utf8.en.md as a rather esoteric example. The software would consider md, en, utf8 suffixes and stop then because beta-released contains a non-alphanumerical character. Although 22 (before the string beta) contains only alphanumerical characters because the suffix extraction had already stopped.

Permalinks

Permalinks are computed from the output location. By default, they are simply the relative path to the site directory. If the filename portion of the output location matches the configured index string (normally index) followed by one or more suffixes the filename is stripped off.

For example posts/en/about-qgoda/index.utf8.md would be translated into the permalink /posts/en/about-qgoda/.

Customization

You can fully customize both output location and permalinks by setting the variables location or permalink respectively in the front matter of an asset, as a default for a certain directory or site wide in _config.yaml.

You can interpolate all kinds of asset variables into the configured string by placing them inside {curly} braces. For example the default configuration for the variable location is /{directory}/{basename}/{config.index}.{suffix}.

The following variables are meaningful for location and permalink customization:

path
The absolute path of the asset.
relpath
The relative path of the asset, without a leading slash.
directory
The directory portion of "path" without a leading or trailing slash. This will be the empty string for assets in the top-level source directory.
filename
The current filename
basename
The basename portion of the filename (without suffix/suffixes).
suffix
The suffix (resp. suffixes) with a leading dot, subject to translation. If there are no suffixes the variable does not exist.
config
The site configuration as read from "_config.yaml"
date
The date of the asset. Do not use directly but one of the subkeys below.
date.epoch
Seconds since the Epoch (00:00:00 UTC, January 1, 1970)
date.year
The four-digit year.
date.month
The two-digit month (01-12).
date.imonth
The month (1-12) without the leading zero.
date.mday
The two-digit day of the month (01-31).
date.imday
The day of the month (1-31) without the leading zero.
date.day
A synonym for "date.mday".
date.iday
A synonym for "date.imday".
date.hour
The hour of the day (01-24).
date.ihour
The hour of the day (1-24) without the leading zero.
date.hour12
The hour of the day (01-12) on a 12-hour clock.
date.ihour12
The hour of the day (1-12) on a 12-hour clock without the leading zero.
date.ampm
The national representation of either "ante meridiem" (a.m.) or "post meridiem" (p.m.) as appropriate. This can be an empty string, depending on the currently selected locale.
date.min
The minutes (01-59).
date.imin
The minutes (1-59) without the leading zero.
date.sec
The seconds (01-60).
date.isec
The seconds (1-60) without the leading zero.
date.dst
The string "DST" (may be translated!) if Daylight Savings Time is in use
location
The computed location of the document. Before the location is computed, the variable is a synonym for "path".
permalink
The computed permalink of the document. Before the permalink is computed, the variable is a synonym for `location`.

Note that variables are not necessarily plain old strings but can be more complicated. Take this example configuration in YAML:

dictionary:
    foo: 1 # dictionary.foo
    bar: 2 # dictionary['bar']
    baz: 3 # dictionary["baz"]
array:
    - Tom    # array[0]
    - Dick   # array.1 also works.
    - Harry  # array['2'], you can also use double quotes.

Quoted strings have JavaScript semantics!