[QUESTION] How to adapt/customize Frontmatter keys

[bellons91]

Hello. I'm trying to port my blog to Statiq, using this theme.

My old blog uses Markdown files with this kind of Frontmatter:

---
title: "3 ways to inject DateTime and test it"
path: "/blog/inject-and-test-datetime-dependency"
tags: ["CSharp", "Tests", "MainArticle"]
featuredImage: "./cover.jpg"
excerpt: "DateTime, Guid, and Random values are not under your direct control. You should abstract them to write better code and testing. We'll see 3 ways to inject and test them in .NET Core projects."
created: 2021-01-12
updated: 2021-01-12
---

I'm looking for a way to adapt the "old" structure with the one required by this theme.

In particular, I'll have to map

• title => Title
• created => Published
• excerpt => Lead

Then, I'll also have to perform 2 transformations:

path must be used as Destination Path ( how can I customize the example DestinationPath: => $"{Document.GetDateTime("Published").ToString("yyyy/MM")}/{Document.Destination.FileName}" ? )

Then, how can I define the cover image for each blog post, using the one defined in the featuredImage field?

[bellons91]

The two approaches that I suppose I could take to solve the first issue (Frontmatter mappings) are:

1. Set some configurations somewhere to tell Statiq.CleanBlog that Title, Published, and Lead are actually called title, created, excerpt.
2. create a custom Statiq module to manually handle such mappings.

Is the first approach feasible? If so, how?

What about the second approach? By reading the documentation, I suppose that I have to write a ParallelModule and, somehow, access Frontmatter values for each document. If so, how?

[daveaglick]

The title to Title one is easy - metadata keys in Statiq are case-insensitive so no action needed :)

Published is a little trickier, it's built into Statiq Web a little bit, so even if your local copy of the theme were updated, it wouldn't quite be the same. That's not to say Statiq couldn't be adapted to use Created instead - it wouldn't be too tough to change the theme and add/replace the functionality in Statiq Web that looks for Published to look for Created instead, but I don't think it's necessary. The easiest solution would just be to use something like EditPad that has a global file-based search-and-replace to find and replace all the instances of created: with Published: in Markdown files. An alternative solution if you don't want to change the Markdown files would be to use directory metadata to define a computed value for all files that maps one to the other:

Published: => GetString("created")

Lead can be handled the same way as Published though you've got another option there since Lead isn't part of Statiq Web at all, just this theme. That means you could also search the theme files for any mention of Lead and replace it there in your local copy of the theme with Excerpt if you like "excerpt" better.

As for setting the destination path, note that it's file-specific (as opposed to URL-like as in your example front matter). In other words, you've need to set something like /blog/inject-and-test-datetime-dependency.html. Converting an .html file to an extensionless URL is the concern of the web host so Statiq doesn't make any assumptions there. Note that it's required if the source files are in a similar path structure either. For example, if Markdown file for this post is at /blog/inject-and-test-datetime-dependency.md then it'll end up with a destination path of /blog/inject-and-test-datetime-dependency.html automatically and you should delete the path front matter entirely. If you still want to define a hard-coded path in front matter, you can do so as a normal YAML string and Statiq will convert it to a DestinationPath automatically (the more complex computed value in that example is only if you need the help of code to figure out the path):

DestinationPath: "/blog/inject-and-test-datetime-dependency.html"

The featured image is entirely a function of the theme as well, and different themes will have different support for something like that. As for CleanBlog, it uses the Image metadata value, so that transition from featuredImage to Images will be the same as for the others. I would consider a global search-and-replace first, then something like directory metadata and a computed value to map from the old key if that's not acceptible.

[daveaglick]

The two approaches that I suppose I could take to solve the first issue

Either could work! One of the main tenants of Statiq is flexibility and extensibility so there's tons of ways to do any given thing. A front matter mapping module hadn't even occurred to me, but it's certainly an option, if not probably a bit more than you need for this (but I like the enthusiasm!).

Hopefully the computed metadata approach in a directory metadata file I mentioned above works for you to test things out quickly. If it doesn't let me know and we'll circle back around.

[bellons91]

Since I have ~150 blog posts, I opted for the _directory.yml mapping.

I successfully managed the porting of Title and Lead (even though, in the homepage, the Lead content appears twice - see below - and I don't know if it's a wrong configuration on my side or it is actually a feature of the theme)

[bellons91]

Now I can tackle the two main issues: URL mapping and Images.

My current structure is

-/articles ---/2023 ------/article folder --------/article.md --------/cover.png --------/another_image.png

Does it mean that I have to transform the whole structure of my blog to keep the old format?

Or maybe I can do something like

DestinationPath: => $"{Document.GetString("path")}/index.html"

(which is currently not working)

[daveaglick]

How is this going? I kind of lost sync after the last round of comments... Have you been successful?