BLOGC-PAGINATION(7)

📦
version 0.20.1^20240602.b1ae9c9 · 3 versions
, in fedora 43

💖 BLOGC-PAGINATION(7) 💖

okay so bestie, welcome to blogc-pagination, section 7 of the blogc manual. this is the page that teaches you how to do pagination without losing your whole entire mind. it's giving ✨organized chaos✨ and honestly? we're obsessed. 🎀

✨ NAME ✨

blogc-pagination — blogc's pagination support 🦋

🌸 DESCRIPTION 🌸

so like, blogc(1) has basic pagination and post filtering built in, but ONLY when it's running in listing mode, okay? don't come for me if you're in some other mode, it's simply not the vibe there. 💅

and listen — the files get listed in the exact order you handed them to blogc(1) on the command line. no sorting, no shuffling, no ✨magic✨. what you give is what you get. periodt.

🎀 PAGINATION PARAMETERS 🎀

blogc(1) accepts these as -D options, and they're the little gatekeepers that filter the files you passed as arguments. iykyk. 👑

  • FILTER_PAGE — an integer, the current page. so if you call blogc(1) with 10 files, FILTER_PER_PAGE=4 and FILTER_PAGE=3, you get just the 2 last files — it skips the first 2 pages of 4 files each one. math is mathing. 🔥
  • FILTER_PER_PAGE — an integer that caps the maximum number of files to be listed. if it's negative or 0, then no posts are included, sorry bestie, empty page energy 💀. and heads up: it has no effect at all if FILTER_PAGE isn't defined.
  • FILTER_TAG — a string. if you define it, blogc(1) will only list files that declare a TAGS variable, written as a space-separated list of tags (and yeah, tags can't have spaces, obviously 🙈). see blogc-source(7) for the deets on defining source variables. the pagination filters will then only act on the files with that provided tag, instead of filtering the whole entire file set. slay.
  • FILTER_REVERSE — boolean (1/y/yes/true/on). if set, blogc(1) lists files in reverse order. this filter is combined with FILTER_SORT, and all the other filters receive the files already in the reverse order. 🔄
  • FILTER_SORT — boolean (1/y/yes/true/on). if set, blogc(1) sorts files using the DATE variable from inside the files, instead of respecting the order of the source files you gave to blogc(1). files get sorted in descending order, and combined with FILTER_REVERSE that results in files sorted in ascending order. all the other filters receive the files already sorted. the way that works is genuinely iconic. ⭐

🦋 TEMPLATE VARIABLES 🦋

blogc(1) also exports some global blogc-template(7) variables so you can build links for the next and previous page. bestie, these are your navigation besties:

  • CURRENT_PAGE — integer, usually the same value as the FILTER_PAGE pagination paramenter (yes that's a typo in the original, we keep it, it's canon 💖), if defined, or 1.
  • FIRST_PAGE — integer, 1 if more than zero files were listed.
  • LAST_PAGE — integer, the 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 also 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 lowkey so useful for knowing the last page you need to build — like with -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, the DATE variable from the first file in the listing.
  • DATE_LAST — string, the DATE variable from the last file in the listing.

these variables can also be formatted with the DATE_FORMAT global blogc(1) parameter, if provided, using the 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, the FILENAME variable from the first file in the listing.
  • FILENAME_LAST — string, the 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. three of them. a whole trio. 👑

⭐ 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 (again, keeping the original grammar, it's part of the lore 💖), but the concept is the same for all of them. no cap. ✨

💀 BUGS 💀

please report any issues to: https://github.com/blogc/blogc

not me putting a bugs section right after the examples but go off i guess. 🙈

👑 AUTHOR 👑

Rafael G. Martins <rafael@rafaelmartins.eng.br>

🎀 SEE ALSO 🎀

and that's the whole page bestie!! this lil masterpiece was written by Rafael G. Martins and it's dated January 2025, living in the blogc manual. go build your paginated site, you absolute main character. 🌈💖✨🎀🦋🌸💅🫶

📦 where this page comes from