blogc-pagination(7) -- blogc's pagination support
=================================================

## DESCRIPTION

blogc(1) supports some basic pagination and post filtering, when running on
`listing` mode. Files are listed in the order that they are provided to
blogc(1) in the command line, no sorting is done.

## PAGINATION PARAMETERS

blogc(1) accepts some variables as `-D` options, that are used to filter the
files passed as arguments to it:

  * `FILTER_PAGE`:
    Integer, current page. If calling blogc(1) with 10 files,
    `FILTER_PER_PAGE=4` and `FILTER_PAGE=3`, it will return just the 2 last
    files, skipping the first 2 pages with 4 files each one.

  * `FILTER_PER_PAGE`:
    Integer, limits the maximum number of files to be listed. If negative or
    `0`, no posts are included. Have no effect if `FILTER_PAGE` is not
    defined.

  * `FILTER_TAG`:
    String, if defined, blogc(1) will only list files that declare a `TAGS`
    variable, as a space-separated list of tags (tags can't have spaces,
    obviously). See blogc-source(7) for details about how to define source
    variables. The pagination filters will only act on the files with the
    provided tag, instead of filtering the whole file set.

  * `FILTER_REVERSE`:
    Boolean (1/y/yes/true/on), if set, blogc(1) will list files in reverse order.
    This filter is combined with `FILTER_SORT`, and all the other filters will
    get the files already in the reverse order.

  * `FILTER_SORT`:
    Boolean (1/y/yes/true/on), if set, blogc(1) will sort files using the `DATE`
    variable provided in the files, instead of respecting the order of the
    source files provided to blogc(1). The files are sorted in descending order
    and combined with `FILTER_REVERSE`, that will result in the files sorted in
    ascending order. All the other filters will get the files already sorted.

## TEMPLATE VARIABLES

blogc(1) will export some global blogc-template(7) variables, that can be used
to build links for next and previous page.

  * `CURRENT_PAGE`:
    Integer, usually the same value of `FILTER_PAGE` pagination paramenter, if
    defined, or 1.

  * `FIRST_PAGE`:
    Integer, 1 if more than zero files were listed.

  * `LAST_PAGE`:
    Integer, last page available if more than zero files were listed.

  * `PREVIOUS_PAGE`:
    Integer, `CURRENT_PAGE` minus 1, if `CURRENT_PAGE` is bigger than 1.

  * `NEXT_PAGE`:
    Integer, `CURRENT_PAGE` plus 1, if `LAST_PAGE` is bigger than `CURRENT_PAGE`.

blogc(1) can output the value of the variables after evaluation, instead of
actually rendering the files, using the `-p` option. See blogc(1) for details.
This is useful to know the last page that needs to be built, using `-p LAST_PAGE`,
for example.

### Date variables

blogc(1) will also export some global blogc-template(7) variables related to
the `DATE` variable, as specified in blogc-source(7).

  * `DATE_FIRST`:
    String, `DATE` variable from the first file in the listing.
  * `DATE_LAST`:
    String, `DATE` variable from the last file in the listing.

These variables can be also formatted with `DATE_FORMAT` global blogc(1) parameter,
if provided, using `DATE_FIRST_FORMATTED` and `DATE_LAST_FORMATTED` global
template variables.

### File name variables

blogc(1) will also export some global blogc-template(7) variables related to
the `FILENAME` variable, as automatically exported by the source file parser,
see blogc-source(7) for details.

  * `FILENAME_FIRST`:
    String, `FILENAME` variable from the first file in the listing.
  * `FILENAME_LAST`:
    String, `FILENAME` variable from the last file in the listing.

## EXAMPLES

### Source file with tags

    TITLE: My post
    TAGS: foo bar baz
    -----------------
    Post content

This source file defines 3 tags: `foo`, `bar` and `baz`.

### Template with pagination

    {% block listing_once %}
    <ul class="pager">
        {% ifdef PREVIOUS_PAGE %}
        <li class="previous">
            <a href="/page/{{ PREVIOUS_PAGE }}/">&larr; Newer</a>
        </li>
        {% endif %}
        {% ifdef NEXT_PAGE %}
        <li class="next">
            <a href="/page/{{ NEXT_PAGE }}/">Older &rarr;</a>
        </li>
        {% endif %}
    </ul>
    {% endblock %}

This example does not uses all the variables, but the concept is the same for
all of them.

## BUGS

Please report any issues to: <https://github.com/blogc/blogc>

## AUTHOR

Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;

## SEE ALSO

blogc(1), blogc-source(7), blogc-template(7)