Why this project exists: allowing for some things I don't think my static site generator supports

I build my websites with a static site generator called Hugo. Even the newest versions of Hugo lack certain features (as far as I have been able to determine), features that I view as rather desriable. I have now implemented some of my wishlist, although there is still plenty more to do.

Making a separate preprocessor project like this has several advantages, as I see things:

• I can make things as quick-and-dirty as I like, without having to deal with the (completely reasonable) rigor that would be expected if I tried to implement things in a PR for the official hugo project. I'm doing this primarily for me (to automate a bunch of stuff in my content workflow), and this is simply the fastest way to make that happen. To be honest, I don't consider myself a hotshot dev (somewhat by choice -- I spend my time on enough other things I never will be, simply on account of my priorities), and thus don't really view a formal PR against the main hugo repo particularly realistic for me. All this to say, I very much appreciate the folks on whose shoulders I stand, but I am not one of them. I'll hack together what works for me and my circumstances, and post it publicly in the hope that it maybe helps someone else. I'll leave the impressive stuff to the folks who have the sort of impressive knowledge and time-commitment required to do it right.
• Building on the above point, I can make things work exactly how I want, without having to worry about the use cases and opinions of others. If I were trying to get all this integrated into the main project, this would not be the case.
• I am comfortable with Python and agree with many of its opinionated language choices, but have never used Go before. I would personally much rather maintain a large Python codebase than large Go codebase.

Right now this project only operates on Markdown hugo sites. I am eying moving my sites back to Org (if I move into Emacs full-time again), and if that happens, I'll probably make an effort to support both content formats.

Things that have now been implemented

Automatically building aggregation pages

There are advantages to keeping page size down. It is faster for users (smaller page sizes mean faster load times). It is generally easier to skim through a table of contents that only contains 5 things than one that contains 40. You get the idea.

However, it can also be useful to be able to skim through larger pages that are aggregations of content: sometimes you might want to be able to see the wider context of how things are laid out. To do that, you'll need to be able to see information about more than one page at a time.

Which content you smash together shouldn't be arbitrary, though. For the aggregation to make sense, it must help organize things for you in some semantically-useful way.

Rolling up collections of pages just makes sense in terms of searching and skimming. But we shouldn't have to do anything to make it happen. It should "just work."

Automatically building HTML slides as an alternative text view of all content

Completely automated construction of markdown content slides based on page content (including an auto-generated TOC for the slideshow presentation, and proper translation of relevant Hugo shortcodes into HTML).

Section-level (rather than page-level) subject-tagging of content

The construction of a subject index that is much more fine-grained than individual pages; supporting categorization tags for every single header on the site (vs. only at the page level). Hugo's Taxonomies (e.g., here) let you set things up per-page using variables in the YAML/TOML frontmatter, but that's pretty useless for pages of substantial size (something that would equal tens of pages in print) where you'd want to subject-tag individual sections or subsections, for much more useful content navigation.

Things that have not yet been implemented

The ability to include some markdown content in other markdown content, no HTML or shortcodes necessary

Many people are probably thinking right about now "why not just use a normal quotation?" Good question. Quite simply, the answer is because the maintainability of hand-copied content is a nightmare, whereas if content is referenced programmatically, it will be updated completely automatically if it is changed in its source location.

I don't want to make a custom HTML shortcode every time I might want to include one piece of markdown content in more than one place. To be honest, I was kind of shocked that straight markdown-to-markdown referencing was not supported out-of-the-box. Anything other than that seems to me to be vastly more inefficient.

I want to do better than making standalone markdown blobs everywhere, though. No, I'd rather be able to seamlessly integrate already-existing content into a new page without even touching the old location. No refactoring should be necessary, and we shouldn't have any unnaturally broken-up content; stringing together smaller standalone markdown files to be re-used seems a lot less intuitive to me than just statically referencing content sections from another complete file that already exists.

Based on this, I want to define a specific API for including:

• An entire page
• A specific section of a page (referenced by header) -- without any nested subheaders
• A specific section of a page (referenced by header) -- including all nested subheaders
• Some range of content on a page (referenced inclusively by fromHeader through toHeader -- toHeader may be semantically under fromHeader, i.e., a subsection of fromHeader)

And then set up references to automatically include exactly the content I want, and have it update seamlessly everywhere whenever I update it in its source location.

Oh, and to make things robust, we need to elegantly handle when header names change too (make it easy to update references broken by renaming headers -- compare links breaking on the internet). It will be unavoidable, but we can make it less painful to deal with with some thought. At least I would imagine so.