Mythic Domains
A Worldbuiding & DIY-RPG Blog
image licensed via stock.adobe.com

Working With Collections

Collections, Categories, Projects.

The site uses collections, groups of content other than posts, to organize information. The support for some of this is automated by the templates but, most likely because of the limitations of my development skills at the moment, there is some manual configuration required when implementing a new collection.

Categories

Because of the decision to not make use of pagination, the site relies on archives to browse content beyond the last 12 blog posts. These supply the titles of all of the posts by date or organized by the tags used to describe them. For additional convenience, certain broader categories exist with their own index pages that a visitor can browse if they are interested in content spanning many tags but containing related material.

Note: The site will allow you to add a category that does not exist to a post. Please be aware, that the automated links to those categories will not work without manual configuration. Only categories that have been set up manually should be used in order to assure site cohesion.

Manual steps for new categories:

  1. Add a category image-set with 21x9 and 1x1 images to /src/img.
    You will need to run gulp build:img to generate the formatted images at the required resolutions to facilitate the responsive design.
  2. Add a category-name.md file to /app/_category.
    Adjust the “Weight” in the YAML frontmatter so that the category will show up in the navigation list (left side on large screens, or above the content on smaller ones) in the order that you want.
    Also, the site currently uses quotes displayed at the top of category pages. Include one, using the same format as in the other category markdown files.
  3. That’s it. The /app/_includes/left.html file will see the new category page and create a link using the category image.

Projects

Projects are a completely different kind of content from posts. Each project is kind of like a book, and the layout is intentionally designed to work more like documentation pages instead of blog posts. The intention of projects is to distill content as it evolves over the course of blog posts and discussions about them and to maintain an “up to date version” of important content. I might have an idea that I later revisit and alter considerably. Both the original idea and the new one exist as blog posts, but the version included in the relevant project is the “canon” version if there is need to be clear on the current state of things.

Manual steps for new projects:

  1. Create a new collection in _config.yml. Make sure to set defaults in that file as well.
  2. Make a 000-00-project-name.md file. This will serve as the first page (or cover) of the documentation.
    There is an example in /templates that includes all the necessary YAML frontmatter.
  3. Prepare a project-name-toc.html file and place it in /app/_includes/cache.
    The contents of the ToC file is not project specific. These files are only unique so that the site only has to build the ToC one time for each project. This means you can just copy the ToC template of another project, and rename the copy to reflect the new project name.
  4. Add a project image-set with 21x9 and 1x1 images to src/img.
    You will need to run gulp build:img to generate the formatted images at the required resolutions to facilitate the responsive design.
  5. Add a category-name.md file to app/_category.
    Adjust the “Weight” in the YAML frontmatter so that the project will show up in the navigation list (left side on large screens, or above the content on smaller ones) in the order that you want. Note that all projects are listed before categories.
  6. That’s it. The app/_layouts/project.html file will see the new category page and create a link using the category image.

Some additional pointers on projects.

  • The additional YAML frontmatter in the 000-00-project-name.md file is used by the site in various ways and must be included.
    • “brand” is used to allow you to provide a correctly title-cased title for the Project on links.
    • “sitemap” tells the site to include the cover page in the sitemap. Other project pages will not be included by default.
    • “permalink” lets you set this as the “index.html” for the category.
  • The other YAML frontmatter allows you to organize the documentation.
    • “section” tells the template that a page has child pages it should process directly under this page.
      Note the template currently only supports one level of child pages.
    • “parent” is the slug of the page that is the parent page of this page. When the template goes looking for child pages, this is how it identifies them.
    • “sequence” is the sort order of pages. The default sorting is numeric, with the format “XXX-XX”. The first three numbers indicate the page’s order in the top most list (individual pages or sections/parents). The two numbers after the dash are the numeric order for child pages.
      In some cases, you may want to organize children alphabetically. This may be important when you may be adding many entries over time, in no particular order, and want to avoid having to renumber multiple files to account for changes. To do this, use “XX” for the second set of numbers, add a dash, and then add the word you want to sort that file by (likely the page title/slug).