{"syenite":[{"meta":{"title":"Mastodon webmentions as comments","description":"Syenite now has support for Mastodon webmentions in lieu of a commenting system","author":null,"author_url":null,"mastodon_toot_url":"https://indieweb.social/@brbcoding/111381002830455161","image":null,"image_credits":null,"published":"2023-11-11T07:30","updated":null,"tags":["syenite","mastodon"]},"path":"/2023/11/mastodon-webmentions","content":"

One of the trickiest problems to solve with a static blog is a commenting system. By its nature, commenting requires a back-end component and some form of persistence, usually in the form of a database.

I feel like a dynamic blog should offer a way for people to interact with the author. It’s probably one of the top reasons holding me back from starting blogs on various subjects, sooner. A dumb reason, at that. Nonetheless, I like interacting with my readership.

This becomes a problem when you’re all-in on hosting everything statically for minimal (or zero) cost. There are commenting systems out there that have a free tier or are self-hosted, but there’s always a catch. Either you are locked into a specific platform, or you eventually exceed the free quota, or there are privacy implications, or you still need to pay for a self-hosted instance.

So I’ve been exploring various ways to add comments to a static blog engine without having to self-host or rely on 3rd parties.

One technique that has gained steam since Twitter collapsed into a pile of shit is using Mastodon webmentions 🔗 as comments. (Another way is to use GitHub issues, but since I’m aiming the first real-world implementation of this engine at non-developers, the Mastodon option wins for now.)

The procedure

The article linked above is everything you need to get this working. Nonetheless, I’m documenting the procedure here, specifically in the context of a SvelteKit blog.

Add the webmention links to the site header

Showing only the additions, omitting existing code

In the main layout file I imported SITE_URL and AUTHOR_URL from the config file and stripped out the http(s):// part. Then I added these 3 link tags to the site <head> element.

src/routes/+layout.svelte

<script>\n    import { SITE_URL, AUTHOR_URL } from '$lib/config.js'\n\n\tconst siteUrl = SITE_URL.replace(/^(https?://)/, '');\n</script>\n\n<svelte:head>\n    <!-- Mastodon webmentions -->\n\t<link href={AUTHOR_URL} rel=\"me\">\n    <link rel=\"webmention\" href={`https://webmention.io/${siteUrl}/webmention`} />\n    <link rel=\"pingback\" href={`https://webmention.io/${siteUrl}/xmlrpc`} />\n</svelte:head>

In the browser this renders as:

<link href=\"https://github.com/breadthe\" rel=\"me\">\n<link rel=\"webmention\" href=\"https://webmention.io/syenite.vercel.app/webmention\">\n<link rel=\"pingback\" href=\"https://webmention.io/syenite.vercel.app/xmlrpc\">

Push the changes to production! The two links must be live in production, otherwise the next step will fail.

Link the blog URL to your GitHub profile

In GitHub edit your profile and add the site URL https://syenite.vercel.app/ to either the website field, or one of the additional Social accounts. In my case, I already had another blog under the main website field.

$\"Mastodon$

Sign in to webmention.io using GitHub

Open webmention.io 🔗 in the browser.
Put the site URL in the Web Sign-in field and hit Sign in

$\"Mastodon$

If everything was setup correctly, you should be redirected to the Settings page https://webmention.io/settings 🔗

$\"Mastodon$

Notice that it shows the two links I already added to the header. It’s fine, we’ve already done the legwork of adding them to <head>.

Link Mastodon account to brid.gy

Go to fed.brid.gy 🔗 and click on “Cross-post to a Mastodon account” to integrate with your existing Mastodon account. In my case that would be https://indieweb.social.

Next it’ll ask for your site URL. For me that would be https://syenite.vercel.app/.

Post a link to the article on Mastodon

On Mastodon make a new post which includes the exact link to the article, https://syenite.vercel.app/2023/11/mastodon-webmentions in this case. Grab the Mastodon toot URL which looks like this https://indieweb.social/@brbcoding/111381002830455161.

Now go back to the article itself and add the URL to the mastodon_tool_url frontmatter. Then publish it again. Once people start replaying / favoriting / boosting your toot, they’ll start appearing on your article.

The cool thing about this is that you’ll be able to see the mentions in your local environment as well (npm run dev), so you can easily debug or adjust the design.

Displaying the webmentions

Now that the blog is wired up with Mastodon it’s time to get any mentions via the webmention.io API and display them at the bottom of each article.

$\"mastodon-webmentions-displayed.jpg\"$

The article page is at src/routes/[year]/[month]/[slug]/+page.svelte.

It imports 2 components for Mastodon webmentions:

src/components/MastodonShareBtn.svelte - renders the Mastodon share button.
src/components/MastodonWebmention.svelte - polls the webmention.io API when the component loads, and renders the webmentions. You can certainly make it refresh periodically if needed, but I think that’s overkill, so I didn’t bother.

Conclusion

Thanks to Coding with Jesse 🔗 I was able to implement Mastodon webmentions on 2 different blogs. This one was even easier than the first, because most of the plumbing was in place. All I had to do was be very careful wiring things up with the 3rd party services, and convert a couple of Vue components to Svelte.

Unfortunately it’s not all roses and butterflies. A couple of people have already pointed out on Mastodon that this type of commenting system has some privacy implications, and now I’m having second thoughts about adding webmentions.

I am torn on this. I love the Mastodon community and chill vibe, and I would like to bring some of that discussion to my blog. It really feels like there’s no good option for integrating blog comments that stands head and shoulders above all others.

My plan is to leave support for it built in since I did the work of implementing it, but add a config flag to turn it off if you want. I mean, it’s likely that no one but me will use this blog engine but still…

"},{"meta":{"title":"Syenite v0.4","description":"New features in Syenite v0.4: deep article search, hero image","author":null,"author_url":null,"image":"syenite-v0.4-hero.jpg","image_credits":"https://unsplash.com/@thethomasensley","published":"2023-11-03T07:30","updated":null,"tags":["syenite"]},"path":"/2023/11/syenite-v0.4","content":"

Syenite v0.4 has been released.

New features

✨ Article search (deep)

There is now a search function in the blog index. As you type, you are searching article titles, meta description, tags, and article content.

The state of the search persists in the URL, so you can share this /blog?search=obsidian+vault for example.

The core search logic is partly based on swyxkit 🔗, specifically this bit https://github.com/swyxio/swyxkit/pull/169/files 🔗. My implementation is simplified, as it doesn’t (yet, or ever?) highlight search results, and it uses a different approach for extracting the article text.

I used several packages for the search feature:

https://github.com/paoloricciuti/sveltekit-search-params 🔗 - makes working with URL search parameters a lot easier
https://github.com/leeoniya/uFuzzy 🔗 - text fuzzy search
https://github.com/html-to-text/node-html-to-text 🔗 - converts HTML to plaintext, to make it more convenient to search through it

✨ Hero image

You can now define a hero image in the article frontmatter, along with image credits. Example:

---\ntitle: Draft article\ndescription: Example of an article in the _drafts folder\nauthor:\nauthor_url:\nimage: example.jpg\nimage_credits: https://example.com\npublished: 2023-09-04T14:30\nupdated:\ntags:\n  - syenite\n---

The hero image is located in _assets. See obsidian-vault-setup. Currently there’s no support for (hot)linking images from external URLs.

There is some basic logic in place that checks if image_credits is a valid URL, in which case it renders it as an anchor, otherwise it’s displayed as plain text.

The OG image meta tags should also use the hero image if it exists, instead of the default generated image.

This very article has a hero image.

"},{"meta":{"title":"Syenite v0.3","description":"New features in Syenite v0.3: Obsidian heading links, external link behavior, and more","author":null,"author_url":null,"published":"2023-10-09T07:30","updated":null,"tags":["syenite"]},"path":"/2023/10/syenite-v0.3","content":"

Syenite v0.3 has been released.

New features

✨ External link behavior (for articles)

External links in articles now have a 🔗 icon attached and open in a new tab. To be considered external, a URL must not be relative, and must be prefixed with http(s)://.

In contrast, internal links are relative links pointing to another blog article.

$\"External$

Here’s how an external Obsidian link is transformed to HTML:

[Frank Noirot](https://franknoirot.co/)\n\n<a target=\"_blank\" href=\"https://franknoirot.co/\" rel=\"nofollow\">Frank Noirot 🔗</a>

Improvements

🛠 Obsidian heading link support

In addition to the Obsidian links supported in v0.1, the following types and patterns have been made possible in v0.3.

v0.1 Simple link to another Obsidian document with optional link text

[[3rd-party-services]]\n<a href=\"/2023/09/3rd-party-services\">3rd-party-services</a>\n\n[[3rd-party-services|3rd party services]]\n<a href=\"/2023/09/3rd-party-services\">3rd party services</a>

v0.3 Link to a heading in another Obsidian document with optional link text

[[3rd-party-services#tailgraph.com]]\n<a href=\"/2023/09/3rd-party-services#tailgraph-com\">3rd-party-services#tailgraph.com</a>\n\n[[url-and-folder-structure#Static pages as `.md` files]]\n<a href=\"/2023/09/url-and-folder-structure#static-pages-as-md-files\">url-and-folder-structure#Static pages as <code>.md</code> files</a>\n\n[[url-and-folder-structure#Static pages as `.md` files|Static pages as .md files]]\n<a href=\"/2023/09/url-and-folder-structure#static-pages-as-md-files\">Static pages as .md files</a>

Key highlight here, beside how awesome it is to link to a specific heading in another article, is that the hashmark text is sanitized and transformed to snake-case, to match the Table of Contents.

💄 Centered images

Article images are now centered.

💄 Full height layout

The main body of each page now expands to the full height of the window regardless of how little content is on the page.

"},{"meta":{"title":"Syenite v0.2","description":"New features in Syenite v0.2: mobile nav, 404 pages, other articles tagged, rewritten tags API, and more","author":null,"author_url":null,"published":"2023-10-04T07:30","updated":null,"tags":["syenite"]},"path":"/2023/10/syenite-v0.2","content":"

Syenite v0.2 has been released.

New features

✨ Mobile main nav

$\"Mobile$

✨ 404s for pages, articles, and tags

Each of these has a personalized 404 Not found page with links to relevant sections of the site.

$\"404$

$\"$

$\"404$

✨ “Other articles tagged” component

Now there’s a new component at the bottom of each article called “Other articles tagged…“. This should help with discoverability.

$\"syenite-v0.2-other-articles-tagged.png\"$

🤔 A few issues I’m debating are:

should I limit the list of articles under each tab to, say, 10?
show the current article in the list (not as a link) or not? This would create multiple entries though, one for each tab. But… it would avoid the scenario where the current article is the only one for a certain tab.

Improvements

🛠 Re-wrote the tags API

The tags API is defined in src/routes/api/tags/+server.js and it now powers 2 things: the /blog/tags (or /blog/tags/sometag) page, as well as the “Other articles tagged…” component.

Originally I had designed the endpoint to be called either

GET /api/tags - for the tags index
GET /api/tags/sometag - for a specific tag

Everything worked fine in dev mode, but when I tried to build for production SvelteKit complained about multiple routes with the same name.

After some experimentation I decided that the best course of action would be to pass the specific tag in a URL query parameter instead of tacking it on to the path. So I ended up with this:

GET /api/tags - for the tags index, no changes here
GET /api/tags?tag=sometag - for a specific tag

Another advantage of this pattern is that down the road it would be very easy to adapt it for filtering by multiple tags instead of just one, so something like this /api/tags?tag=sometag,anothertag.

I also disabled prerender in src/routes/+layout.js which had previously been true. Prerendering doesn’t work with URL query parameters. Attempting to npm run build throws this error:

Error: Cannot access url.searchParams on a page with prerendering enabled

The changes combined made everything come together nicely, and the site feels very snappy, even without prerendering.

💄 Blog index visual reorg

I reorganized the blog index visually. Probably doesn’t matter at this point since this project is meant as a starter that every person should customize to their own preference but whatever 🤷‍♂️

Before

$\"Blog$

After

$\"Blog$

After - mobile

$\"Blog$

Fixes

🐞 Fixed images containing `.` in the file name

If an image (located in article-vault/_assets) was named syenite-v0.2-mobile-menu.gif it would break the site, as the logic in src/lib/utils/index.js would try to split the file name by . and lose the middle part in the process.

"},{"meta":{"title":"3rd party services","description":"Useful third-party tools & services that contributed to building Syenite","author":null,"author_url":null,"published":"2023-09-29T14:30","updated":null,"tags":["syenite","tools"]},"path":"/2023/09/3rd-party-services","content":"

tailgraph.com

https://tailgraph.com/ 🔗

Generate Open Graph 🔗 images with Tailwind CSS.

For example here’s the URL that generates the images for one of the blog articles.

https://og.tailgraph.com/og?fontFamily=Poppins&title=Obsidian%20vault%20setup&titleTailwind=font-bold%20text-blue-600%20text-7xl&text=Setting%20up%20the%20Obsidian%20vault%20for%20Syenite&textTailwind=text-gray-700%20mt-4%20text-2xl&textFontFamily=Roboto&logoTailwind=h-8&bgUrl=https%3A%2F%2Fwallpaper.dog%2Flarge%2F272766.jpg&bgTailwind=bg-white%20bg-opacity-30&footer=https%3A%2F%2Fsyenite.vercel.app&footerTailwind=text-gray-600

wallpaper.dog

https://wallpaper.dog/ 🔗

A free wallpaper service that swyxkit 🔗 uses (and so do I now) for OG image backgrounds (see example above).

webpagetest.org

https://www.webpagetest.org/ 🔗

Test website performance, loading, rendering speed, etc.

"},{"meta":{"title":"Obsidian vault setup","description":"Setting up the Obsidian vault for Syenite","author":null,"author_url":null,"published":"2023-09-28T14:30","updated":null,"tags":["syenite","obsidian"]},"path":"/2023/09/obsidian-vault-setup","content":"

I described briefly in syenite-building-blocks how Obsidian links are transformed to HTML.

I this guide I’ll talk about how to setup your Obsidian article vault.

My implementation assumes that the Obsidian vault is co-located with the blog codebase. Ideally, the two should be separated, so that you could keep the blog and vault in different repos and link them via a reference.

swyxkit 🔗 has that, but I think the way it does it is too complicated. For that reason, I decided to start simple using co-location and see if I can improve it down the road.

Implementation

The Obsidian vault is named article-vault and is hardcoded at the moment. article-vault is referenced in these places:

src/routes/[year]/[month]/[slug]/+page.js
vite.config.ts
src/lib/utils/index.js

My intention is to make it 1) configurable in config.js and later 2) separate it entirely from the blog engine into its own repository.

Folder structure

For now, this is what the vault folder structure looks like.

$\"obsidian-vault-structure.png\"$

The vault itself is located in /src. Within, there are 4 subfolders of interest:

_assets contains any images that you link in articles. For example horse-head.png is referenced in markdown-showcase.md using Obsidian syntax.
_drafts should be used for draft articles that are not yet ready to be published. When ready, move them to one of the [year]/[month] folders.
.obsidian is created automatically by Obsidian, contains Obsidian’s settings for the vault, and is ignored by default. If you want to add it to version control, feel free to remove it from .gitignore.
2023/09 etc is the article structure. I explained how I ended up with this structure in url-and-folder-structure. Ultimately it’s not too hard to make this flat (or whatever you fancy), just keep in mind that this engine is opinionated, and this is what works for me.

"},{"meta":{"title":"Config file","description":"How to configure global site parameters using the config file","author":null,"author_url":null,"published":"2023-09-26T14:30","updated":"2023-11-09T07:30","tags":["syenite"]},"path":"/2023/09/config-file","content":"

There is a file called src/lib/config.js that exports several constants used in various places, in lieu of hardcoding those values.

It goes without saying you shouldn’t keep any sensitive information here such as API keys.

These are the supported parameters and their default values.

Parameter	Default value
SITE_URL	`'https://example.com'`
SITE_TITLE	`'Syenite'`
SITE_DESCRIPTION	`'Static blog engine with SvelteKit + Obsidian'`
DEFAULT_OG_IMAGE	`SITE_URL + '/og.jpeg'`
AUTHOR	`'breadthe'`
AUTHOR_URL	`'https://github.com/breadthe'`
AUTHOR_TWITTER_HANDLE	`''`
WEBMENTION_IO_API_URL	`'https://webmention.io/api/mentions.jf2'`
AUTHOR_MASTODON_SERVER	`'https://indieweb.social/'`
AUTHOR_MASTODON_HANDLE	`'@brbcoding'`

You can import any of these parameters in any file with

import { AUTHOR, AUTHOR_URL } from '$lib/config.js'

Any asset referenced from the root, such as og.jpeg can be found in /static.

"},{"meta":{"title":"Syenite wishlist","description":"Future features that are planned or desired","author":null,"author_url":null,"published":"2023-09-24T14:30","updated":"2023-10-08T09:30","tags":["syenite"]},"path":"/2023/09/syenite-wishlist","content":"

This is a list of features that I would like Syenite to have. None of these is guaranteed, but it’s good to track them in one place. The list is roughly in the order of priority I would like to tackle them.

If you haven’t already, check out the current features.

For more detailed notes, check out the v0.2 and v0.3 releases.

Content/SEO

“Latest (10) articles” component, to be used on landing page and/or bottom of each article

General

Article search
Mastodon mentions
Blog index pagination
More configurable parameters in config.js
Separate article-vault repo from blog engine
utteranc.es 🔗 integration
Article reading time estimator
- see https://github.com/lbenie/reading-time-estimator 🔗
- see implementation https://github.com/hendrikmitk/hendrikharlichs/blob/main/src/routes/notes/%5Bslug%5D/%2Bpage.ts 🔗
Syenite icon :)

Styling

Page transitions (see https://joshcollinsworth.com/blog/sveltekit-page-transitions 🔗)
Proper code highlighting
Dark mode scroll bars

Fixes

Navigating to a link with a hashmark (heading link) doesn’t refresh or re-initialize the table of contents on that page. This is a problem with the TOC library I am using (explicitly mentioned in the docs 🔗).
~~Internal links should have the full URL in the href, not just the relative path, so instead of /2023/09/markdown-styling I want http://example.com/2023/09/markdown-styling~~ Actually I think I’m ok with relative links for now.
Handle double Updated scenario (when both updated frontmatter is set and the UpdatedAt component is used in the same article). Not super high priority, since this can be handled simply by not using the Updated component.

"},{"meta":{"title":"URL and folder structure","description":"How the folder-based URL structure was designed","author":null,"author_url":null,"published":"2023-09-23T14:30","updated":null,"tags":["syenite"]},"path":"/2023/09/url-and-folder-structure","content":"

Page URLs

These are simple - just the SvelteKit defaults. So for the blog index, just go to

https://example.com/blog

In addition, this template ships with several more pages: /about, /uses, /contact, and /tags ( a “hidden” one not linked in the main nav).

Article URLs

Naming things is hard, including such a simple thing as “article” or “post”. Ultimately I landed on “article”, which conveys a dash more artistry despite being longer.

https://example.com/2023/09/syenite-blog-engine

But why the ugly prefixes?

For a long time I struggled with the concept of whether I should prefix article slugs with year-month- or not, or whether I should nest them like they currently are. I had to choose between these options, with pros and cons for each.

https://example.com/syenite-blog-engine
https://example.com/blog/syenite-blog-engine
https://example.com/blog/2023/09/syenite-blog-engine
https://example.com/2023-09-syenite-blog-engine
https://example.com/2023/09/syenite-blog-engine

How article URLs are resolved

First thing you should know, as a SvelteKit developer, is that the article page (or “shell” if you will) is nested in

src/routes/[year]/[month]/[slug]/+page.svelte

The article data is provided by

src/routes/[year]/[month]/[slug]/+page.js

Ignoring certain import folders (assets & drafts)

The logic for getting all the markdown articles is defined in src/lib/utils/index.js in the fetchMarkdownArticles function.

I’ve set this up so that it ignores imports from the _assets and _drafts folders. Until an article is ready to be published it can be kept safely in _drafts and you won’t have to worry that it will be included.

The ability to ignore importing from certain folders is given by this Vite feature 🔗.

Static pages as `.md` files

You can, indeed use a .md file as a top-level page instead of .svelte.

Here’s what my /uses page defined in src/routes/uses/+page.md looks like:

<script>\n    import Heading from '$components/Heading.svelte'\n\timport '$css/markdown.css';\n</script>\n\n<Heading>Uses</Heading>\n\n<article class="markdown-body">\n\nWrite markdown here\n\n</article>

The only caveat is that you should wrap your markdown content in <article class="markdown-body"> to benefit from proper styling.

"},{"meta":{"title":"Syenite building blocks","description":"A high level overview of how Syenite is constructed","author":null,"author_url":null,"published":"2023-09-22T14:30","updated":"2023-10-08T14:30","tags":["syenite","obsidian"]},"path":"/2023/09/syenite-building-blocks","content":"

At the highest level, Syenite is built on SvelteKit 🔗, with Vite 🔗 and Tailwind CSS 🔗. But there are more bits and pieces that make it work.

mdsvex

mdsvex 🔗 is what allows Svelte code to exist and be executed from markdown files. This is cool because it allows dynamic components in markdown pages and articles, if you need it.

One example in Syenite is the src/components/UpdatedAt.svelte component.

You might wonder why would I need such a component when I can just get the updated timestamp from the frontmatter. Well, that’s because sometimes I want the updated date to be “evergreen”, in other words to always show today’s date. Bbbut why?? I have a very specific thing in mind for the future (I said this engine was opinionated af, didn’t I?).

Swyxkit

I lifted and adapted many parts from Swyxkit 🔗. I like a lot about that engine, but it’s a bit too feature-packed for me, plus it lacks a few things I want. Here are some things I poached.

the dark/light toggle (src/components/DarkModeToggle.svelte)
RSS (src/routes/rss.xml/+server.js) and sitemap (src/routes/sitemap.xml/+server.js)
the table of contents (src/components/TableOfContents.svelte)
the head metadata stuff - tedious and boring stuff, glad someone else has handled it

Obsidian integration

In theory, using Obsidian to write articles sounds straightforward. Just point the vault to a folder inside the blog codebase and start writing. Then SvelteKit + mdsvex takes care of the rest, right?

Well, not so fast. There’s the not-insignificant matter of internal document references that need to be converted to URLs, with a similar thing for images and other assets.

In other words, we want to convert links:

[[syenite-blog-engine|Syenite an opinionated blog engine]]\n\n👇\n\n<a href="/2023/09/syenite-blog-engine">Syenite an opinionated blog engine</a>

and images:

![[horse-head.png|Horse head]]\n\n👇\n\n<img src="/assets/horse-head.png" title="Horse head" alt="Horse head">

This is not trivial. So rather than shattering my brain trying to figure it out, I thought “surely someone else must have done it already”. Thankfully, a developer named Frank Noirot 🔗 did the legwork and wrote an article about it https://github.com/franknoirot/obsidian-sveltekit-blog/ 🔗.

While he only implemented document links (anchors), as soon as I made the first rough prototype I realized that images work differently. The heavy lifting had already been done so all I had left was to add very similar code to deal with images.

This logic can be found in src/lib/utils/index.js. The code may look messy, and some of it is repeating, but it’s all good - it works and that’s all that matters!

Read more about setting up the Obsidian vault.

This doesn’t work… yet

One Obsidian feature that is unsupported (it will throw a compile error) is referencing headings in an article.

This

[[syenite-blog-engine#The Frankenblog|Syenite blog engine]]

should resolve to

<a href=\"/2023/09/syenite-blog-engine#the-frankenblog\">Syenite blog engine</a>

Similarly, a heading containing inline code such as

[[url-and-folder-structure#Static pages as `.md` files|URL and folder structure]]

should resolve to

<a href=\"/2023/09/url-and-folder-structure#static-pages-as-md-files\">URL and folder structure</a>

Packages

https://github.com/remarkjs/remark-html 🔗 - extracts HTML from markdown, used for the RSS feed
https://github.com/paoloricciuti/sveltekit-search-params 🔗 - makes working with URL search parameters a lot easier
https://github.com/leeoniya/uFuzzy 🔗 - fuzzy search for articles
https://github.com/html-to-text/node-html-to-text 🔗 - extracts text from HTML (article HTML is first processed using remark), used for searching article content

Other

Additionally, Syenite uses several tools and services to make life easier.

"},{"meta":{"title":"Syenite features","description":"All the features supported by the Syenite blog engine","author":null,"author_url":null,"published":"2023-09-21T14:30","updated":"2023-10-08T09:30","tags":["syenite"]},"path":"/2023/09/syenite-features","content":"

These are all the features that the Syenite blog engine currently offers. Check out the wishlist for planned or desired features.

Authoring

Write articles in markdown 🔗
mdsvex 🔗 allows Svelte components in markdown
Use Obsidian 🔗 to author articles, with support for:
- linking other Obsidian documents in the same vault
- linking images in the same vault
- linking headings in another document
YAML frontmatter 🔗 for article metadata
Create pages with Svelte components (see /about) or markdown (see /uses)
Create drafts in _drafts and drag them to the corresponding [year]/[month]/ when the article is ready to be published

General

Blog index (/blog) with:
- articles sorted in reverse published order (latest first)
- article blurb based on description frontmatter
Article tags with tags index (/tags)
RSS feed (/rss.xml)
Sitemap (/sitemap.xml)
Light / dark mode with persistence in localStorage
Mobile main nav
Linkable article headings
Automatic table of contents from article headings (H1, H2, etc)
Links to the previous and next article at the bottom of each article
Configurable Author name & URL, overwritten in frontmatter
Page/article header metadata and open graph 🔗 tags
TypeScript support, although I’ve made zero effort to implement anything in TS

Content/SEO

Hero image in frontmatter
“More articles tagged xxx” at the bottom of articles

Styling

Tailwind CSS
GitHub markdown styling, customizable using CSS tokens
Mobile-friendly / responsive layout
Colors defined with CSS tokens in the main stylesheet (app.postcss)
PostCSS support
Separate visual treatment and behavior of internal vs external links. External links have a 🔗 icon attached and open in a new tab. To be considered external, a URL must not be relative, and must be prefixed with http(s)://.

"},{"meta":{"title":"Syenite blog engine","description":"The how and why behind the Syenite blog engine","author":null,"author_url":null,"published":"2023-09-20T14:30","updated":null,"tags":["syenite"]},"path":"/2023/09/syenite-blog-engine","content":"

YASBE - Yet another static blog engine?

“But why?” you might ask. The answer is simple, though the journey is arduous.

I’ve had an idea for a fitness blog for a very long time. Two things stopped me: the inability to find a good (available domain) name, and the right engine.

Because I’m a programmer and a maker, and one is never satisfied with what’s already out there, a new blog engine is born. But fear not, young padawan. While the path of the database-backed blog is tempting, the road there is full of perils.

Who is it aimed at?

Primarily the content creator who is comfortable with npm and git and deploying to a provider such as Netlify or Vercel. It doesn’t hurt to know or be willing to learn Svelte(Kit).

Initially this is not intended specifically for developer blogs, because it’s not the first thing I need from it. The reason for that is that code highlighting is not fully supported, nor is it my first priority.

Eventually, I intend to add proper code highlighting, because I would very much like this to be a great dev blog alternative. For now, think of it as a general blog platform for the developer’s other hobbies.

Base requirements

I am very partial to static blogs, to the point where I will twist into pretzels to have one rather than using a database-driven engine.

Static blogs are easy to manage, can (should) use markdown 🔗, and can be hosted for free.

Over the last 1.5 years I’ve been using Obsidian 🔗 intensely for notes, and while they do offer a publishing platform (at a cost), I thought it would be very cool to use it as a back-end for my own blog platform.

So my absolutely-must-have features for a new blog are:

free & open-source
static
self-managed and hosted
markdown
write articles with Obsidian

Platform options

I considered several technologies before landing on the current implementation.

Laravel Jigsaw

Jigsaw 🔗 is a great option if you live in PHP-land (like me). In fact, I’ve been running a blog on it for years. It uses markdown, is highly customizable, and it generates a static bundle that you can host for free (mine is deployed on Netlify).

The problem is that I failed to keep it up to date and dependencies kinda fell out of sync, so now I’m afraid to touch it in case the production build breaks. But I don’t have a huge reason to fiddle with it either 🤷‍♂️

Another niggle is that it has both PHP and JS dependencies, so there are 2 dependency bundles to stay on top of.

Overall Jigsaw remains a solid choice, and I’m very tempted to make yet another blog on it, with Obsidian support.

WriteFreely

WriteFreely 🔗 is a very tempting engine. At one point I was ready to make the plunge. I love how clean and simple it looks, and that it’s open-source. The fact that it’s written in Go is a blessing (fast) and a curse (I don’t know anything about Go, so potentially hard to host/customize).

The problem with this engine is that, while they do offer a self-hosted edition, it means I have to provide my own server, be willing to perform the installation, and manage it afterwards.

Ultimately I decided that the risk of being stuck on an unfamiliar platform that I also have to manage wasn’t worth it. I’m “lucky” that I’m already paying for a $5 VPS that I use to host dynamic sites, but others may not want the expense.

Custom thing made in SvelteKit

The last thing an aspiring blog writer wants to do is build their blog engine. Unless they’re a programmer, of course. SvelteKit 🔗 was released recently and it was at the top of my candidate list.

So I checked what SvelteKit engines were out there, and the one that stands head and shoulders above the rest is swyxkit 🔗. I thought, this is perfect! A couple of snags though. First, swyxkit is opinionated. It fits most of my requirements, but not all. It also has extra things that I don’t need. Second, it doesn’t have Obsidian support, and I really wanted that.

I did another round of looking around and I came upon this blog template 🔗 by a fellow named Frank Noirot 🔗 built on SvelteKit with Obsidian support. It’s kinda experimental, but it does exactly what I need.

The Frankenblog

I followed this tutorial 🔗 for a while to get a handle on how a markdown blog works on SvelteKit, after which I decided the best thing to do is to stitch together bits from swyxkit and Frank Noirot’s Obdisian technique to get what I want.

Thus was born Syenite.

Remember how I said that swyxkit is opinionated? Well, so is Syenite. It’s opinionated in my own fashion, of course, but that’s the beauty of open-source.

Why Syenite?

Finally, you might wonder why call it Syenite? The reasons keep piling up.

I’ve been reading The Broken Earth 🔗 trilogy by N.K. Jemisin and I really liked the feisty personality of one character named Syenite.

In real life, Syenite 🔗 is an igneous rock similar to granite. I find it beautiful in its simplicity. I want this engine to be simple and solid as a rock (lofty goals, I know).

Incidentally, it doesn’t hurt that both syenite and obsidian are volcanic rocks.

Finally, let me hit you with this knowledge: Syenite and Svelte both start with S and and in te 🤯

"}]}

The procedure

Add the webmention links to the site header

Link the blog URL to your GitHub profile

Sign in to webmention.io using GitHub

Link Mastodon account to brid.gy

Post a link to the article on Mastodon

Displaying the webmentions

Conclusion

New features

✨ Article search (deep)

✨ Hero image

New features

✨ External link behavior (for articles)

Improvements

🛠 Obsidian heading link support

💄 Centered images

💄 Full height layout

New features

✨ Mobile main nav

✨ 404s for pages, articles, and tags

✨ “Other articles tagged” component

Improvements

🛠 Re-wrote the tags API

💄 Blog index visual reorg

Fixes

🐞 Fixed images containing . in the file name

tailgraph.com

wallpaper.dog

webpagetest.org

Implementation

Folder structure

Content/SEO

General

Styling

Fixes

Page URLs

Article URLs

But why the ugly prefixes?

How article URLs are resolved

Ignoring certain import folders (assets & drafts)

Static pages as .md files

mdsvex

Swyxkit

Obsidian integration

This doesn’t work… yet

Packages

Other

Authoring

General

Content/SEO

Styling

YASBE - Yet another static blog engine?

Who is it aimed at?

Base requirements

Platform options

Laravel Jigsaw

WriteFreely

Custom thing made in SvelteKit

The Frankenblog

Why Syenite?

🐞 Fixed images containing `.` in the file name

Static pages as `.md` files

#syenite