site_opytex/plugins/hierarchy/README.md

Page Hierarchy

Author: Ahmad Khayyat (akhayyat@gmail.com)

A Pelican plugin that creates a URL hierarchy for pages that matches the filesystem hierarchy of their sources.

For example, to have the following filesystem structure of page sources result in the URLs listed next to each file,

└── content/pages/           #   PAGE_DIR
    ├── about.md             # URL: pages/about/
    ├── projects.md          # URL: pages/projects/
    ├── projects/            #   (directory)
    │   ├── p1.md            # URL: pages/projects/p1/
    │   ├── p2.md            # URL: pages/projects/p2/
    │   └── p2/              #   (directory)
    │       └── features.md  # URL: pages/projects/p2/features/
    └── contact.md           # URL: pages/contact/

you can use this plugin with the following Pelican settings:

# pelicanconf.py
PAGE_URL = '{slug}/'
PAGE_SAVE_AS = '{slug}/index.html'
SLUGIFY_SOURCE = 'basename'

When generating the url and save_as attributes, the plugin prefixes the page's slug by its relative path. Although the initial slug is generated from the page's title by default, it can be generated from the source file basename by setting the SLUGIFY_SOURCE setting to 'basename', as shown in the settings snippet above. The slug can also be set using PATH_METADATA.

This plugin is compatible with Pelican translations.

Parent and Children Pages

This plugin also adds three attributes to each page object:

• parent: the immediate parent page. None if the page is top-level. If a translated page has no parent, the default-language parent is used.

• parents: a list of all ancestor pages, starting from the top-level ancestor.

• children: a list of all immediate child pages, in no specific order.

These attributes can be used to generate breadcrumbs or nested navigation menus. For example, this is a template excerpt for breadcrumbs:

<ul class="breadcrumb">
  <li><a href="{{ SITEURL }}/" title="{{ SITENAME }}">
    <i class="fa fa-home fa-lg"></i>
  </a></li>
  {% for parent in page.parents %}
  <li><a href="{{ SITEURL }}/{{ parent.url }}">{{ parent.title }}</a></li>
  {% endfor %}
  <li class="active">{{ page.title }}</li>
</ul>