Cards
Even a small website needs a way of organizing content and pages. Xanthan comes with a few ways to do this, and of course more can be added.
Table of Contents
One familiar approach is to create a table of contents for your site pages, like you’d find in a book. Let’s say you have a collection of pages, like student essays for a class project, for which you want to create a table of contents. We can do this automatically, as long as each page has a little metadata at the top of the file in the YML header. It looks like:
---
title: Seedling
author: Fred Gibbs
summary: Perfect for beginners getting comfortable with Markdown and digital essays. Basically section headings, a few images, and some pull quotes. Nothing fancy, but enough to make a visually compelling essay.
---
We can use this data to automatically generate links to the essays, like this:
It’s not magic! We just need to tell Xanthan to create some links based on the metadata that’s found on pages in a specified folder. In this case, it’s Xanthan’s scrollstories folder, but you’ll create your own folder with a descriptive name. We use a little bit of “pseudo-code” to do this. It looks weird at first, but it makes sense once you get used to the syntax.
{% assign card_pages = site.pages | where_exp: "page", "page.path contains 'scrollstories/'" %}
{% include card-toc.html rows = card_pages %}
- First, we define a variable called
card_pages(it could be called anything) that gathers all the metadata from the files in the essays folder. That’s what thepage.path contains 'scrollstories/'part does. - Then we send that data to our include file (card-toc.html), which has the actual HTML code to generate the cards themselves. This way, we create very consistent code on our pages and if we want to change how it looks, we have to edit only one file.
- You can copy and paste this code on any page where you want to link to other pages. Just change
scrollstoriesin the code to the folder where your pages are. Then you’ll see the “card” links as above.
Stacked cards
A little fancier than a ToC-style list, we can a generate of a stack of horizontal “cards” in the same way. In terms of gathering data to display, this works exactly like above. But it calls a different include file, which presents a stack of wide and short cards in a vertical display.
{% assign stacked_cards = site.pages | where_exp: "page", "page.path contains 'scrollstories/'" %}
{% include card-stack.html cards = stacked_cards %}
Optional Tags
You can group and label similar content with tags in page metadata. Let’s say you have a set of podcasts from a personal podcast or class project, and you want to a make a list of those.
To keep things organized (always good practice!), I put pages that describe and present the podcast in a podcasts folder. It’s always good to use semantically useful folder names, and avoid mysteries like mystuff-2.
---
title: My First Podcast
author: Fred Gibbs
summary: This is my first episode summary. Delicious!
tags:
- history
- technology
- education
---
Grid cards
You can see more cards at a glance if you use a grid layout with slightly smaller cards.
{% assign stories = site.pages | where_exp: "page", "page.path contains 'scrollstories/'" %}
{% include card-grid.html cards = stories %}
You can easily customize how the cards appear depending on what kind of content you want to display in them.
Happy fiddling!