Publish: Posting

In the 2nd part of this series, we looked into creating and understanding a custom Publish theme. If you haven't read that part already, I recommend reading it before continuing here.

In this part, we'll dive deeper into posts and their metadata.

Let's dive right in.

Anatomy of a Post

Consider the first-post.md file that was created automatically when you created the site:

There are 2 sections to understand here:

1. The content between the 2 --- lines
2. All the content below the 2nd --- line

The first section is called the front matter. This section contain all the metadata of your post. For example, it contains the date, the description and the list of tags.

The second section is the body of your post. This is where you'll be writing your markdown content, using all the markdown syntax you know and love.

Custom Metadata

As you might think, the date, description and tags are great, but they are a little bit limited. Let's say you'd like to keep the date of a post but would also like to include a "last udpated" date. This way, the user reading your post can understand that the post was created some time ago, but was recently updated with the latest information.

Using the existing front matter, you wouldn't be able to do that. Even worse, using your custom theme to do this would be a mess; you'd have to hard code the date value for each post in the Swift code. 🤮

There's a better way.

Updating ItemMetadata

If you recall the anatomy of main.swift, there's an ItemMetadata struct that we can leverage to add custom information:

You can add as many properties as you need here. The front matter items you will add will translate into these properties (using Codable, make sure to add your coding keys if needed), and will be made available to you in the theme factory methods.

Let's add an updated property:

And let's update the post:

And then, let's run the site (using mint run publish run):

Ok, well, that's a little underwhelming. Nothing shows up?!

The metadata is there, but nothing uses it yet. So let's start making modifications to our theme.

Modify Your Theme

If you recall, the Theme+Hello.swift file contains all the functions to generate your site. However, almost everything in that file uses generics:

That's great and all, but our project doens't contain multiple sites. Wouldn't it be great to get access to our types and not just the generic types? Wouldn't it be also awesome to get autocomplete working? Let's do just that by removing all the generics from our theme:

I haven't included it here in order to keep things succcinct, but you also need to remove any other reference to Site and <Site> in order types with HelloPoblish and <HelloPublish> respectively.

You can try to run your site (using mint run publish run) and everything should be working as before.

If you recall, the makeItemHTML(for:context:) function is the one generating the HTML for your posts.

There are no references to the word "date" and definitely nothing referencing the new metadata item we added. Let's change that by adding a couple of div elements:

Ok, now let's build and run again:

Great success! 😎

It doesn't look great, but it works just as intended. Now you can go ahead and style this as much as you want.

Conclusion

The metadata section isn't limited to dates. In fact, since it's using Codable, you can add any kind of data you want. For example, for this site, I've added a header image, a thumbnail image, and an updated date. I've even added a property to exclude drafts from the published version of the site.

As you can see, you have all the power that Swift can offer, and you can customize the generation processa as much as you need.

In the 4th and final part of this series, we'll look into actually publishing your site using GitHub.

Don't forget to tell someone you love them.
Cheers! 🍻