Why?
This website is developed using 11ty (Eleventy). It's a super simple static site generator written in Javascript that I tried recently, and loved right away.
Obsidian is an open source markdown note-taking tool. It's minimal, it's super simple, it's works flawlessly for all kinds of content writing (if you're a fan of markdown). I've used it for a few years for basically everything.
This setup makes it much easier and frictionless to write content, especially since I'm able to utilize Obsidian plugins and all of its other awesome features.
TLDR
Eleventy is used as the static site generator for this site. Inside my posts collection folder I've opened a Obsidian vault. Each new post consists of a markdown file and an image folder.
I'm using the Obsidian templater plugin to generate new posts with default frontmatter meta data that Eleventy uses. Images are directly pasted into a post and are automatically saved to the image subfolder of the post.
I'm also able to modify Obsidian to my liking using CSS snippets. Having a beautiful writing experience makes writing more fun.
Getting started
This website is split into a few collections of content:
- Projects
- Posts
- Templates
Each section is placed in its own content folder. Projects and Templates are rarely updated and are therefore not needed to integrate with Obsidian right now.
Posts, however, is a collection that I intend to update regularly. That's why I've created a new Obsidian vault inside this folder.
Post setup
A post consists of:
- A folder for the whole post
- A markdown file for all the content and meta data
- A folder for the images of the post
Inside VSCode it might look something like this:
Inside Obsidian it might look something like this:
Frontmatter / Meta data
Frontmatter contains all the meta data of a post. In my case, the frontmatter for each post consists of:
- Title
- Description
- tags
- date
- reading time
- layout
- optionally a couple more things
This is needed for Eleventy to understand how to categorize a post, where to display it and so on. It's also needed for SEO-reasons and reading experience etc.
In Obsidian, frontmatter variables are called attributes. These can be added manually to a document through its settings. This is however very time consuming and boring, so that's where the first Obsidian plugin comes in handy.
Obsidian plugins
I just recently found out about these amazing resources. The Obsidian community seems to be very active in developing plugins that solve even the most niche problems. These are easily installable through the software itself.
Obsidian Templater (plugin)
The templater is a plugin that can automate lots of stuff. I'm however using it for one thing and one thing only - to create new posts from a template.
This template is a simple markdown file located in a templates folder in my vault. It looks something like this:
It's a default post with all needed attributes (frontmatter) that I can duplicate on demand.
In order to create a new post, I'll create a new folder and use Obsidian's quick command thingy (ctrl + p), and find the templates: insert template button.
Images
All images gets automatically saved inside a subfolder called img. The default location of saved images can be configured in the settings.
Image captions
There isn't any official markdown image caption syntax that renders HTML figure & caption elements. This can however be fixed by installing the NPM package markdown-it-image-figures and configure it with 11ty.
You can find a full guide for this over here (written by Al Power). There are a couple things not mentioned in the guide though:
- You need to install both markdown-it and markdown-it-image-figures in your 11ty project
- You need to pass a html parameter as true in the options for the plugin in order for the markdown to properly render HTML
Paste Image Rename (plugin)
Naming images seems to be important in order for Obsidian to find the relative path to them. Why? I don't know. But you basically have to name them without spaces etc.
That's when the Paste Image Rename plugin comes in handy. Obsidian names images in strange way as a default. This plugin simply prompts you to name each image when pasting it in. Great.
Publishing
I'm using Github & Netlify to store and deploy this site. Each commit gets pushed to my Github repo which in turn triggers Netlify to rebuild the site.
I know that there is a Git plugin for Obsidian that could automate pushes and therefore act as a publishing "button", but I haven't had time to take a look at that one yet.
Instead I just manually push changes every now and then through my terminal for now.
Current quirks I'd like to solve
- Image figure captions While creating figure captions is possible in Obsidian using plugins, it doesn't create them in a way that 11ty can understand and properly render as HTML. Why is that? Edit: This is now solved above.
- Standard markdown image syntax When pasting in an image into an Obsidian document, the syntax it uses to display images is strange. This means that I have to manually correct it for every pasted image.
- Image compression I've tried every Obsidian image compression plugin there is, and none of them seem to be able to save images in custom folders. This needs to be fixed.