Folder Data Files & Waypoints

If you're familiar with Lume, you probably already know what's up; everything below is just reference to you (I try to keep the examples up to date with what's live on this site).

For those that are new to Lume, archetypes are scripts that Lume runs which can create base content for blog posts, content pages, photo galleries, or whatever other content you have.

In Cushy Text, this applies to three specific types of content that the theme knows how to generate:

• blog : A blog with a working tag system, feeds, tag wiki, tag feeds and archives. Supports multiple instances with independent tags.

• docs : Like a blog, but sidebar is auto generated, no archive pages, tag pages, or author pages. Shows content rating form by default. Meant for technical articles.

• pages : Full-page, sidebar-less MDX pages that aren't auto-linked, but can be tagged and are searchable. Meant for creating long-form content, galleries, presentations, landing pages, company branding or whatever. Essentially the default when no archetype is specified in data.

A special file called _data.yml(these are important in Lume) in each directory controls default frontmatter settings for everything in that directory, and directories inside of it; this is a base feature of the generator.

Cushy Docs takes advantage of this by looking for special configuration directives that control how things get generated. Cushy Docs decides if the files in the current directory are a blog, a documentation collection, or a collection of content pages depending on settings contained in these files, and then generates things differently.

To give you an idea of how this works, right now, you're actually in /docs, which is a docs archetype (a documentation area, not robust like a blog). Let's take a look at the _data.yml file inside this directory, which affects this directory, and all directories within it:

layout: layouts/docs.vto
waypoint: "%theme-docs%"
type: docs

docs:
  basedir: /docs/
  title: Cushy Theme Docs
  sidebar: auto
  guest:
    heading: "Latest Blog Post:"
    waypoint: "%blog%"
    posts: 1

This file instructs Lume "for every file in this folder, apply these (...) settings" while the theme template picks up on the presence of docs: and adjusts accordingly to switch layouts, generates the nav, etc.

That special waypoint key is what I call a, well, waypoint. It lets me run multiple installations of docs while including content from each install by a friendly name.

If I wanted to get all content from all docs installs, I would use an internal search query of type=docs. However, if I want just results from this documentation, the theme docs in /docs, I would use waypoint=%theme-docs%.

Now, let's take a look at the blog directory _data.yml file:

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

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

This works similarly to docs, but gives me a separate way to scope the content with behind the scenes: %blog%. It also makes sure tags is at least set, even if it's just an empty array, to avoid onerous checks in templates.

It's designed to allow running multiple blogs on the same site. For example: one for content, one just for release notes. Currently, only one centralized /archive for tags and authors is supported, but generators along with templates they should use will be configurable per-blog in a near release.

What About "pages"?

The pages archetype is under construction and will depend on finishing all of the components so that they can be made available as MDX elements.

Right now, there's plenty of utility stuff, but no real page-building stuff in the mix yet. That's coming up soon!

Creation Scripts Included

You'll find blog.ts, doc.ts and page.ts included in src/_archetypes, they're the bare minimum needed to qualify for having them. I plan to add some additional arguments, or the ability to create by waypoint, but it's low on the priority list.