Full-Featured Blog System

The blog system is primarily controlled through settings in the _data.yml file of the root blog directory. Cushy Text supports having multiple blogs.

The blog object controls both aspects of how the blog is generated, but also how the instance will be scoped in searches from other parts of the site. Here's an example _data.yml file from this blog, identical to the default that ships with the template:

layout: layouts/post.vto
type: blog
waypoint: "%blog%"
tags: []

blog:
  basedir: /blog/
  title: Cushy Text Blog
  recent: 3

Let's talk about this file.

Understanding Data In Lume, In General:

Take a look at the Lume docs on shared data.

The _data.yml sets frontmatter properties for the current directory, and all directories within it. It's a great way to set default values that never change from page to page, or a way to build more complicated processing steps, like rendering a blog. Individual files can set their own values, these values are just here so they don't have to be set deliberately every time.

The First Part Controls Generation.

I'm telling Lume to use the layout I designed for individual blog posts, that it should associate the word "blog" with a page property called type, and that I want this content revealed when I search for a waypoint property called %blog%.

Having multi-blog in mind, being able to turn up all posts with a type of blog doesn't let me narrow my search per-blog, so waypoint is what provides the additional precision.

I also initialize tags[] to be an empty array so I don't have to test for it existing in my template code, just potentially empty.

The Second Part Controls Blog features.

The blog property controls (and, in templates, reveals) basic aspects about the blog installation, most substantively the basedir setting, which allows access to knowing where in the URL structure you are within navigation scripts.

The rest simply controls the instance's index page title, along with how many posts should be displayed on the instance's index page.

Tag Wiki System & Tag Feeds:

A "Tag Wiki" is a concept of bringing more useful information to the generated /archive/tag-name/ index pages. They're controlled by having a presence in the src/_data/tagWiki.yml file, with the announcements tag as an example:

announcements:
  summary: >
    The announcements tag is applied when there's a major announcement
    to make, such as a new release or other major news about the project.


    It's not used very often, so if you subscribe to a feed and see
    the tag, it's probably worth checking out.
  related_tags: ["updates"]

If you click on the example link, you'll also see the "Related" section, which is what's controlled by the depicted related_tags property of the tagWiki.yml file.

Tag wikis can be created by you, or by your community submitting pull requests against that file. The incentive to do this is to enable tag feeds, which are RSS feeds generated independently for each tag.

The actual generation happens in plugins.ts where the feed component is loaded, but it takes the presence of the tag wiki to show them. I did this so that people didn't subscribe to feeds that were prone to vanishing - establishing the tag with a wiki only happens when a tag is going to stick around.

This system could conceivably also add SEO benefit, if the content is useful, relevant, substantive and original. It helps the goal of helping projects rank slightly higher in their own search terms.

MDX By Default.

Use components anywhere you like, with the ease of familiar MDX.

Roadmap For The Blog Feature:

Right now, /archive is hard-coded and generated by two generators in (wait for it ...) src/generators, which hone in on waypoint=%blog% to make sure they only generate pages for this installation.

So if you made blog2/, you'd need to make copies of those page generators and edit them to use whatever waypoint you assigned to blog2/ instead.

That's not a huge ask, but it's not ideal. I'd like to be able to control generators (and aspects of how they work) a lot more in the blog's _data.yml file.

This is possible, just too much for the first release. Probably in the third.