Paligo components and helpers

Paligo gives templates ready-made components for common parts of a page, and a few helper functions and filters. A component produces complete, accessible HTML that you style with your own CSS. You can also build the same parts yourself from the Template variables.

Components

Function	Produces	Produces nothing when
`paligo_search_box()`	A search box. See Search in a theme.	The layout has no search engine.
`paligo_breadcrumbs()`	A breadcrumb trail.	The page is at the top level.
`paligo_toc()`	A list of the headings on the page.	The page has no headings.
`paligo_pager()`	Links to the previous and next pages.	There are no previous or next pages.
`paligo_language_switcher()`	Links to the site in its other languages.	The site has one language.

<header>{{ paligo_search_box() }}</header>
<aside>{{ paligo_toc() }}</aside>
<main>
    {{ paligo_breadcrumbs() }}
    {{ page.content }}
    {{ paligo_pager() }}
</main>

The class names to style:

Component	Markup
`paligo_breadcrumbs()`	`<nav class="paligo-breadcrumbs">` containing an `<ol>`. The current page is the last `<li>`, with `aria-current="page"`.
`paligo_toc()`	`<nav class="paligo-toc">` containing nested `<ul>` lists of links.
`paligo_pager()`	`<nav class="paligo-pager">` containing `<a class="paligo-pager-prev">` and `<a class="paligo-pager-next">`.
`paligo_language_switcher()`	`<nav class="paligo-language-switcher">` containing a `<ul>`. The current language's link has `aria-current="true"`.

Note

The texts in paligo_pager() and the accessible names of these components are in English. For a site in other languages, build the pager from page.prevPage and page.nextPage with site.strings.navPrev and site.strings.navNext, as shown in Template variables.

Write your own language menu

paligo_language_switcher() produces a plain list. To show the languages in your own way, such as a dropdown in the header, build the menu from site.languages. This example shows the current language's name, and opens to a list of every language:

templates/partials/language-menu.html.twig:

{% if site.languages|length > 1 %}
  {% set current = site.languages|filter(l => l.code == site.lang)|first %}
  <details class="language-menu">
    <summary aria-label="{{ theme.strings.changeLanguage|default('Change language') }}">
      {{ current.label|default(site.lang|upper) }}
    </summary>
    <ul>
      {% for language in site.languages %}
        <li>
          {% if language.code == site.lang %}
            <a href="#" aria-current="true" lang="{{ language.code }}" hreflang="{{ language.code }}">{{ language.label }}</a>
          {% else %}
            <a href="../{{ page.translations[language.code]|default(language.code ~ '/') }}" lang="{{ language.code }}" hreflang="{{ language.code }}">{{ language.label }}</a>
          {% endif %}
        </li>
      {% endfor %}
    </ul>
  </details>
{% endif %}

Include it where the menu goes:

{% include 'partials/language-menu.html.twig' %}

How the example works:

The menu is shown only when the site has more than one language.
site.languages has each language's code, and its label, the language's name in that language, such as Deutsch. The current page's language is site.lang.
The current language is marked with aria-current. The lang attribute lets screen readers say each name in its own language.
Each other language links to the same page in that language when Paligo knows it, from page.translations, and otherwise to that language's front page. This is what paligo_language_switcher() does too.

Use <details> and <summary> as in the example, and the menu opens and closes without a script.

Helper functions

asset(path) gives the link to a file in the theme's assets/ folder. See Theme assets.

paligo_contrast_color(background, dark, light) returns whichever of dark and light is easier to read on background, using the WCAG contrast ratio. dark defaults to #161617 and light to #ffffff. Use it to pick a text color that works with a color chosen in a theme option:

<div class="hero" style="background: {{ theme.options.accent }}; color: {{ paligo_contrast_color(theme.options.accent) }}">

All three colors must be hex colors, such as #3a46e8. If one isn't, the function returns an empty value.

Filters

excerpt(length) turns HTML into plain text and shortens it to at most length characters, at the end of a word, adding "…" when it shortens it. The default length is 160.

<meta property="og:description" content="{{ page.content|excerpt(200) }}">