Andrew Stiefel | coding

Building a personal monorepo for writing

2025-07-19T00:00:00-07:00

I use Obsidian to organize my thinking and writing. But I’ve always been dissatisfied with the process of turning what I write into a formatted post for my website. I either had to manage multiple vaults—adding complexity and violating one of my core principles of note-taking—or copy, paste, and edit my writing in another tool like VS Code.

I also prefer to keep my content separate from the website’s design, and I wanted to do that without introducing a CMS or additional tooling. Static site generators like Jekyll are great at converting Markdown into websites, but they usually require you to store content alongside all the other website files.

After some experimenting, I landed on a better solution: building a personal monorepo for my writing and publishing workflow.

Why use a monorepo?

A monorepo—short for monolithic repository—combines code for multiple projects into a single repository. A common pattern is to store both frontend and backend code in one place.

That’s actually a good analogy for how I think about writing. The “backend” is my Obsidian vault, where I research and take notes. The “frontend” is the website where I publish finished posts.

Basic Setup

To start ,I moved my Obsidian vault and Jekyll website into a new personal-monorepo directory structured like this:

~/personal-monorepo
          ├── /notes
          └── /website
          

If you don’t already have an Obsidian vault or Jekyll site, you can easily replicate this from scratch. Install Obsidian, open the /notes directory using the “Open folder as vault” option, and you’re ready to go.

Setting up Jekyll requires a bit more technical work, but you can find installation instructions here.

Configuring Obsidian

For this approach it’s important to make a directory where you will only store published posts. I’m going to use /notes/posts for this tutorial but you can configure this directory any way you wish.

I also recommend installing two Obsidian community plugins:

Obsidian Git – adds version control and makes publishing easy
Obsidian Permalink Opener – lets you open post URLs in your browser for previewing

For Git, you can push commits manually or set up periodic syncs. For the Permalink Opener plugin, I added both my website’s base URL and my local development URL so I can preview posts in the browser while editing.

With that we’re ready to move on to building our website.

Connecting Jekyll and Obsidian

By default, Jekyll looks for posts in /website/_posts. But I want it to use the content in /notes/posts. The simplest solution is to create a symbolic link.

First, open Terminal and make sure you’re in the root of your monorepo (~/personal-monorepo). Back up your content, then delete the existing _posts directory:

rm -rf website/_posts

Next, create a symlink that points to your Obsidian posts:

cd website
          ln -s ../notes/_posts _posts
          

Note: Folder names in symlinks are case-sensitive. If your Obsidian vault uses Posts instead of posts, your symlink won’t work with the above command. Folder names must match exactly.

Publishing with Netlify

Netlify provides first-class support for working with monorepos, but you’ll need to do a little additional configuration.

In your project dashboard or netlify.toml file, set the base directory to website, and make sure the build command installs dependencies before running Jekyll:

Here’s what my full netlify.toml looks like, and what is reflected in my dashboard:

[build]
          base = "website"
          command = "bundle install && bundle exec jekyll build"
          publish = "_site"
          

Netlify follows symlinks automatically, but Jekyll needs one extra setting. In your website/_config.yml, add:

# Enable access to symlinked content
          lax_symlink_lookup: true
          

This lets Jekyll access files stored outside its root directory (e.g. the website folder). Without the site will build but won’t pull in your content from the notes/_posts directory.

Final Workflow

I have Obsidian configured to add new notes to my writing inbox under the ~inbox directory. Anything I start writing goes there. Once I’ve finished writing a note, I can then either move it into my permanent notes or add it to the posts directory if I want to publish it. Once I push the commit Netlify will build and publish my site.

While I’m writing, I can preview what the note will look like by starting the Jekyll development server (bundle exec jekyll serve) and adding the note to the posts directory. I can use the Obsidian hotlinks command to open a preview of the post in my browser.

To wrap up, your final workflow looks something this this:

Write, edit, and link notes in Obsidian
Commit and push changes to Github
Netlify will pick up the changes and publish your posts

Bonus: Convert Backlinks to Weblinks

It’s outside the scope of this post, but I also wrote a custom plugin to convert backlinks to web links. That way I can use Obsidian’s backlinks within my published posts.

You can grab the code here.

Additional Resources

How I use GitHub as a CMS

2025-02-02T00:00:00-08:00

I use Jekyll to build and publish my blog on Netlify. For a long time my content management system (CMS) was just a bunch of markdown files on my laptop. Most of the time I don’t need anything else — it’s simple, and it’s just me.

But as I’ve wanted to focus on writing more often, I wanted to find an easier way to track future ideas, what I’d like to work on now, and easily see what I’ve done.

That’s where GitHub comes in.

Why?

GitHub is built for software development, but many of the features work just as well for content development. In fact, is has about everything I need as you’ll see in my setup section below. This includes templates, project boards, and workflows for publishing.

Plus it’s easy to review and collaborate with other people. I don’t do that much as a solo writer, but I do get readers who spot typos or who share feedback—and then it’s easy to track and add their contributions.

But let’s be honest — this is one of the projects I took on because I could, not so much because it really saves me any time. Choose your adventure accordingly :)

Basic setup

If you’re already using GitHub to host the code for your blog (like I do with Jekyll), then you can get started with this in 15 minutes or less!

Create a project: Go to the GitHub repository for your blog (or make a new one!) and select projects and create your project.
Choose a format: GitHub projects lets you customize views of items in your project using a Kanban board or table format. I recommend starting with the Kanban format. You can always change this later.
Organize your workflow: Once you’ve created your project, take a couple minutes to configure your workflow. I have sections for no status (my backlog), in progress, ready, and done.

You can see an example of mine on GitHub, or with the screenshot below:

Use issues to track posts

Once you’ve created the basic structure, it’s time to start tracking your writing! You’ll want to create new issues so you can track your progress. I decided to create a new template so I wouldn’t have to add the same info every time.

If you’d like to create one, all you need to add is a markdown file in your repository at the location below:

.
          ├── .github 
          │   └── ISSUE_TEMPLATE
          │      └── cms.md
          

Here’s an example of what mine looks like:

---
          name: cms
          about: Submit an idea for the blog
          title: "[blog post] "
          labels: cms
          assignees: ''
          ---
          **What is this post about?**
          **Outline**
          1. 
          **Tasks**
          - [ ] Write outline
          - [ ] Draft blog post
          - [ ] Find (1) reviewer
          - [ ] Create pull request
          

I use the format [blog post] example title so I can see at a glance that the issue covers a new blog post, and roughly what it’s about. I provide a brief description (usually when I first have the idea). Later I’ll come back and outline the post.

Writing and publishing posts

Jekyll comes with basic structure which makes it easy to get started. I save my draft writing in the _drafts folder and move finished posts into the _posts folder.

.
          ├── _drafts 
          ├── _posts
          

But you have a few options to customize your workflow a bit further:

Work directly in your main branch and publish by moving the your finished drafts from the _drafts folder to the _posts folder.
Create a new branch for each post as you work and merge into your main branch when you’re ready to publish.

JEKYLL TIP You can preview your posts in your development environment as you work! Just append the --drafts flag to the build or serve command. For example, jekyll serve --drafts. Each draft post will be added using the last modified time as the publication date.

I prefer to create a new branch and to submit a pull request when I’m ready to publish (although I’ll admit, I’m not super consistent since it’s just me). Either way, when you’re ready to publish, you’ll close the issue for your blog by writing a commit message that includes the number of the issue. For example, when I published this blog, I used “Closes 212” to tell GitHub to mark the issue as done.

Now if you visit your project, you’ll see your post has automatically been moved to the “done” column!

Final thoughts

I’ve been exploring ways to customize this further by creating new views — for example, a table view that adds publication dates so I can when I want to publish a post. But most importantly, I’m enjoying the flexibility and close integration between what I write and how it’s published.

Working with multiple GitHub accounts and SSH keys

2024-05-09T00:00:00-07:00

I have multiple GitHub accounts – one for work, one for demos, and one for personal projects. Each has a unique email address, password, and 2FA associated with it. They also each have a unique SSH key. In fact, the SSH keys are all saved in different 1Password accounts (personal, demo, and work).

In some cases I perform the development on the same device, like when I’m building a demo on my work device. In that case I need to make sure that I’m using the correct GitHub account and SSH key.

I use 1Password as my SSH agent because it keeps the private keys off my device, plus it makes authorizing SSH connections a breeze. I can authenticate a connection using Touch ID, so just a fingerprint touch on my keyboard and then I’m off to my next task.

Fortunately, this only takes a few minutes to setup!

Organize your local directory

All my repositories are saved under a GitHub folder and then I use directories to organize my projects by account. Although I prefer to keep personal and work separate, you could configure all three accounts for a single device like in the example below:

~/github
          ├── /demo
          ├── /personal
          └── /work
          

This will make it very easy to configure which profile and SSH key to use in the following steps.

Set your global gitconfig file

In this example, I’m setting my personal Git configuration as the global default. Using [includeIf] I specify a different .gitconfig file for the demo and work directories.

[user]
          name = <github_personal_name>
          email = <github_personal_email>
          signingkey = <your_ssh_key>
          [gpg]
          format = ssh
          [gpg "ssh"]
          program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"
          [commit]
          gpgsign = true
          [includeIf "gitdir:~/github/demo"]
          path = ~/github/demo/.gitconfig
          [includeIf "gitdir:~/github/work"]
          path = ~/github/work/.gitconfig
          

Create gitconfig files for each directory

Next I’ll create .gitconfig files and save them in the demo and work directories. I’ll use a similar template, but this time I’ll provide the GitHub name, email, and public signing key for my demo and work accounts.

[user]
          name = <github_work_name>
          email = <github_work_email>
          signingkey = <your_ssh_key>
          [gpg]
          format = ssh
          [gpg "ssh"]
          program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"
          [commit]
          gpgsign = true
          

Configure the SSH agent

In order to call the correct SSH keys, I’ll need to update the SSH agent config file located at ~/.ssh/config.

I start by setting the 1Password SSH agent as the default for all hosts. Then I create custom hosts for each account, in this case Demo, Personal, and Work.

Next, I downloaded the public keys from 1Password for my demo, personal, and work accounts. I renamed each file (for example, demo_git.pub) and saved the all to my ~/.ssh/ folder.

# By default, use the 1Password SSH agent for all hosts
          Host *
          IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
          # Demo GitHub
          Host gh-demo
          HostName github.com
          User git
          IdentityFile ~/.ssh/demo_git.pub
          IdentitiesOnly yes
          # Personal GitHub
          Host gh-personal
          HostName github.com
          User git
          IdentityFile ~/.ssh/personal_git.pub
          IdentitiesOnly yes
          # Work GitHub
          Host gh-work
          HostName github.com
          User git
          IdentityFile ~/.ssh/work_git.pub
          IdentitiesOnly yes
          

Reset your local repositories

Finally, I’ll need to reset each individual repository so it uses one of the hosts specified above. This will make sure it uses the correct SSH key to authenticate with GitHub and when pushing Git commits.

git remote set-url origin <host>:<organization>/<repository>.git

Finally, run git remote -v to confirm that Git is using the correct remote repository. You can run git fetch to confirm that 1Password offers up the correct SSH key for authentication.

Resources

Configure Multiple Git Signing Setups (1Password)
Use Multiple GitHub Accounts (1Password)
Adding a New SSH Key to Your GitHub Account (GitHub)
Register a Public SSH Key with GitHub (1Password)
Testing Your SSH Connection (GitHub)
Switching Remote URLs from HTTPS to SSH (GitHub)
Optimize Your Git Setup: Strategies for Handling Multiple GitHub Accounts (Dev.to)

Build an email subscription form with Netlify Functions

2022-08-28T00:00:00-07:00

I enjoy the process of building and maintaining my own personal website. It’s a great way to experiment with different technologies, and have fun learning new tools and concepts along the way.

This time, I wanted to learn how to use serverless functions. There are a lot of great resources out there already. But I had trouble finding a guide that adequately addressed my use case: a humble email subscription form.

This tutorial is strongly inspired by an excellent guide created by Matthew Ström. I’ve added solutions for some of the problems I encountered while following his guide, but Matthew deserves the credit.

After going through all the work to build my personal website, the last thing I wanted to do was slap a pre-designed newsletter subscription form on it.

I wanted the flexibility to design my own custom forms for a few reasons:

Better design: Email marketing providers offer great default forms, but they never perfectly match a site’s design
Better Performance: External email forms require additional calls for CSS and Javascript, and they sometimes get blocked by privacy settings
Better privacy: Hosted email forms can collect additional information about users, like their IP address

I set out a few rules for this challenge:

It should work without extra JavaScript or AJAX
It must use Netlify functions
It shouldn’t need external dependencies

The Team: Jekyll, Netlify, and ConvertKit

My website is built using a static site generator called Jekyll. It allows me to build my own templates and components, so I’ll use it to build my email form. I also used Tailwind CSS Forms Plugin to simplify the design process.

I use a service called Netlify to deploy my website. It’s key for this project, because it complies the static assets built by Jekyll and runs the serverless function to send emails to my email list provider.

Finally, I’m using ConvertKit as my email list provider. I’ve also included information on how to use Buttondown and SendStack in this tutorial, but the basic principles of the function should apply to any other email providers that offers an API.

Ok, let’s get started!

Create the serverless function

You need to follow three basic steps to create a Netlify function:

Add API tokens to Netlify as environment variables via the admin interface
Tells Netlify where to look for your functions using the netlify.toml file 3. Write the function in a Javascript file in your project
Write the function as a Javascript file in your project

To start, let’s save the API token from our email service as an environment variable. Environment variables are useful to hold information that I don’t want to make public, like this API key. You can add an environment variable using the Netlify admin interface under your build and deploy settings.

Next, specify where Netlify should look for your functions. Edit your netlify.toml to specify the functions directory. It might look something like this:

[build]
          base = "."
          [functions]
          directory = "netlify/functions/"
          

Create a function file in the directory you specified above. If you used the default functions directory, you should save your function at YOUR_BASE_DIRECTORY/netlify/functions.

Next, you’ll need to give your function a name. For example, to create a function with an endpoint name of hello-world, save the function in one of these locations:

netlify/functions/hello-world.js
netlify/functions/hello-world/hello-world.js
netlify/functions/hello-world/index.js

For this tutorial, I’m going to use the submission-created event trigger. Netlify will run my function every time a form is submitted. To do that, I’m going to name my function submission-created.js.

Now you’re ready to start writing the function. Start by importing the API key you created earlier as an environment variable:

const { EMAIL_TOKEN } = process.env
          

On line 2, I add a small library called node-fetch. This allows me to use Javascript’s Fetch API, which is how we’ll format an API POST request to send data to our email service.

import fetch from 'node-fetch';
          

NOTE: When I was writing this post, many of the tutorials available used the require method to import the Fetch API which resulted in errors when I tried to deploy the function. Make sure you use the method I described above. If you upgrade to node-fetch v3, you’ll also need to update either your netlify.toml file or package.json to use ESM.

[functions]
          node_bundler = "esbuild"
          

You can find more information about how to make a fetch request using node-fetch v3 in an excellent guide by Tatyana Novell on the Netlify blog.

Next create a synchronous function on line 4. The exports.handler value is where Netlify expects to find the function, so I define it there. The basic syntax to create the function is provided below:

exports.handler = async function (event, context) {
          // your server-side functionality
          };
          

Next retrieve the email from the event value using JSON.parse:

const email = JSON.parse(event.body).payload.email
          

Then log the data in the console for debugging:

console.log(`Received a submission: ${email}`)
          

After retrieving the email address from the event value using JSON.parse, I’m ready to send it off my email marketing providers. I’ll use the node-fetch library I imported earlier to form the POST request.

I’ve outlined code examples for a few services below, but make sure you consult the API documentation from your email provider to make sure the API request is properly format.

ConvertKit Subscription Form

Using ConvertKit as an example, send a POST request to https://api.convertkit.com/v3/forms/<YOUR_FORM_ID/subscribe.

To find the form ID, navigate to Grow > Landing Pages & Forms, select the form you want to use, and copy the ID number from the url:

https://app.convertkit.com/forms/designers/<YOUR_FORM_ID>/edit

The body of the POST request contains the email token and the email address from the form submission:

const response = await fetch( 'https://api.convertkit.com/v3/forms/<YOUR_FORM_ID/subscribe', {
          method: 'POST',
          headers: {
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ 
          api_key: EMAIL_TOKEN,
          email: email
          }),
          });
          

Buttondown Subscription Form

Buttondown’s API sends the authorization in the headers rather than the body, so you’ll need to adapt the code slightly:

const response = await fetch( 'https://api.buttondown.email/v1/subscribers', {
          method: 'POST',
          headers: {
          Authorization: `Token ${EMAIL_TOKEN}`,
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ email }),
          });
          

SendStack Subscription Form

SendStack is a new privacy-first email service. Unlike Buttondown and ConvertKit, they offer API access on their free plan. There is currently a waiting list, but if you have access, you can try it out using the code below.

Add the email token to the headers and the email address to the body of the POST request:

const response = await fetch( 'https://getsendstack.com/api/subscribers', {
          method: 'POST',
          headers: {
          Authorization: `Bearer ${EMAIL_TOKEN}`,
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ email }),
          });
          

Then capture and log the response from the email service. We do this to diagnose any issues that happened. Netlify makes it easy to check your function’s logs, so use console.log often!

let responseText = await response.text();
          console.log('Response:', responseText);
          

Finally, redirect the form to a confirmation page that tells subscribers to check their emails to confirm their subscription. Use a simple return to redirect the browser to the new page:

return {
          statusCode: 302,
          headers: {
          'Location': '/confirmation/,
          },
          }
          

You can find the completed function below. In this case I used ConvertKit:

const { EMAIL_TOKEN } = process.env;
          import fetch from 'node-fetch';
          exports.handler = async (event, context) => {
          const email = JSON.parse(event.body).payload.email
          console.log(`Received a submission: ${email}`)
          const response = await fetch (
          'https://api.convertkit.com/v3/forms/{YOUR_FORM-ID}/subscribe', {
          method: 'POST',
          headers: {
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ 
          api_key: EMAIL_TOKEN,
          email: email
          }),
          }
          );
          let responseText = await response.text();
          console.log('response:', responseText);
          return {
          statusCode: 302,
          headers: {
          'Location': '/confirmation/',
          },
          }
          }
          

Create the email subscription form

Now that you’ve built the function, let’s call it from the email subscription form. The HTML for the email subscription form is very minimal.

All you need to do is call the function using the form action:

<form name="newsletter" method="POST" action="/.netlify/functions/subscribe-email">
          <label for="email">Your Email Address</label>
          <input type="email" name="email" placeholder=Email Address"/>
          <button type="submit">Subscribe</button>
          </form>
          

Make sure you specific input name (“email”) and make sure it matches the information you parse from the event value using JSON.parse.

If you used the submission-created trigger for your function like I did, you’ll need to change the <form> field slightly by adding data-netlify="true" to tell Netlify to process this form:

<form name="newsletter" method="POST" data-netlify="true">
          <label for="email">Your Email Address</label>
          <input type="email" name="email" placeholder=Email Address"/>
          <button type="submit">Subscribe</button>
          </form>
          

Deploy the function

Now that I’ve written my function, configured my netlify.toml file, and added my environment variables, everything is ready to go. Deploying is painless: just set up Netlify’s GitHub integration, and your function will be deployed when your project is pushed.

Conclusion

It took less than 50 lines of code to create my own email subscription form including custom HTML and a serverless function to add new emails to my list. I wrote it all in HTML, CSS, and JavaScript, and everything is served from my domain. Plus, my website visitors get a nice experience whether they have JavaScript enabled or not, and it will still serve even if they have advanced privacy protection enabled.

How to style an Atom feed with XSLT

2022-01-24T00:00:00-08:00

Maybe it’s nostalgia for the early web, but I love web feeds as a tool for following and reading content. Feeds are privacy-first and put the reader in control: you can opt out any time, choose your tool for reading, and organize them in any way you want.

But the UX experience is terrible.

Web feeds are meant to be machine-readable, so most users follow a link to an RSS or Atom feed and end up looking at something like this:

This doesn’t have to be the case. RSS and Atom feeds can be human-readable with a little extra work. Here’s an example from my website. It’s simple and clean and provides some essential instructions on how to get started:

Let’s explore how to implement this with Atom and an XSLT stylesheet.

Why Atom, and not RSS?

Great question, and one I don’t intend to answer fully here given the vast amounts of writing on this topic already. In short, Atom is a better format.

Specifically, I wanted the following:

Support for a full content payload in the feed
Wide support across feed readers
Extensibility and future-proof format

First, create the feed in Jekyll

If you’re using a different tech stack to create your website, you can skip this section and jump ahead to the part about creating an XSLT stylesheet.

You can either use the excellent Jekyll Feed plugin, or create your own template using liquid tags and save it in your project as feed.xml.

I chose to create my own template, so I could incorporate some additional markup. You can see my version below:

---
          ---
          <?xml version="1.0" encoding="utf-8"?>
          <?xml-stylesheet href="/assets/css/feed.xsl" type="text/xsl"?>
          <feed xmlns="http://www.w3.org/2005/Atom">
          <title>{{ site.title }}</title>
          <link href="{{ site.url }}{{ site.baseurl }}/feed.xml" rel="self"/>
          <link href="{{ site.url }}{{ site.baseurl }}/" rel="alternate"/>
          <subtitle>{{ site.description }}</subtitle>
          <updated>{{ site.time | date_to_xmlschema }}</updated>
          <id>{{ site.url }}/</id>
          <author>
          <name>{{ site.author.name }}</name>
          <email>{{ site.author.email }}</email>
          </author>
          <rights type="text">Copyright © {{ site.time | date: "%Y" }} {{ site.author }}. All rights reserved.</rights>
          {% for post in site.posts %}
          <entry>
          <title>{{ post.title }}</title>
          <link rel="alternate" href="{{ site.url }}{{ post.url }}"/>
          <updated>{{ post.date | date_to_xmlschema }}</updated>
          <id>{{ site.url }}{{ site.baseurl }}{{ post.id }}</id>
          <summary>{{ post.description }}</summary>
          <content type="html">{{ post.content | xml_escape }}</content>
          </entry>
          {% endfor %}
          </feed>
          

Note on YAML Front Matter block: It’s important to leave the dashes at the top of the file. This is necessary because Jekyll will not process a page with Liquid unless there is a YAML block at the top of the file.

Enable auto-discovery: Make sure you add the appropriate meta tag to support automated discovery of your feed. Place the following code somewhere in your template’s <head> section to output the necessary metadata:

<link type="application/atom+xml" rel="alternate" href="{{ site.url }}/feed.xml" title="{{ site.title }}" />
          

Create the XSL file to style the feed

We can use XSLT to style our XML. This makes our feeds more human-readable while supporting bots, aggregators, and search engines.

You’ll notice some similarities to HTML and CSS in the example below, but with a few semantic changes and special attributes.

First, you can place your CSS in the <style> tag like normal. You can also use some standard HTML markup like the <body>, <section>, <p>, and <h1> tags.

There are a few special elements you can use, like <xsl:apply-templates> or <xsl:value-of>. I won’t cover these in detail during this tutorial, but W3Schools maintains a great XSLT reference if you want to learn about all these special elements.

This Github Gist shows an example of the XLST stylesheet I created for my website. I wrote some basic CSS styles to format it, but you could even tap into your site’s primary CSS file to keep the styling consistent.

Save your file as feed.xsl and add the tag below to your XML file. Make sure the href tag points to the correct location and file name for your website.

<?xml-stylesheet href="/feed.xsl" type="text/xsl"?>

Conclusion

With a little extra care and attention, we can improve the experience of using RSS and Atom feeds across the web. Now when you visit my feed, you are greeted with an explanation of how to get started and a formatted recap of my latest posts.

I made my own XML template and XSLT stylesheet based on the examples above. You can see it in action here or download a version to adapt for your website.

Thanks for reading!

Additional Reading

How I built my blog with Jekyll and Netlify

2021-12-20T00:00:00-08:00

I’ve been blogging and hosting my website since 2006, but I’ve always been unhappy with the themes available for technologies like Blogger, WordPress, or Squarespace. I usually had a vision for what I wanted to create and would spend hours scouring marketplaces to find something that came close.

At first, I experimented with developing child themes for WordPress. If you’re not familiar with WordPress, I basically overwrote the CSS stylesheets and built my own page and post templates using PHP. I even got good enough that I had clients who would hire me to make changes to their WordPress themes and installations.

Still, all of the tweaks and changes felt cobbled together. They were cobbled together. I was building Frankenstein sites with dozens of overrides, plugins, and hacks that could break at any moment.

Searching for something better

I wanted to escape the bloat of platforms like WordPress, or the restricted design options available with a platform like Squarespace. I wanted to go back to static HTML and CSS and I wanted to code it myself.

After reading online, I came across Jekyll. It’s an open-source static site generator. That means it complies basic text files into static HTML so you don’t have to code every page by hand.

I built a few starter projects with Jekyll and quickly fell in love with it. While there are a variety of open-source static site generators available now, I still enjoy the relative simplicity of Jekyll for getting started. The liquid templating language is easy to understand and your HTML/CSS/JS work cleanly together.

Jekyll may not be the sleekest option — there are good reasons to pick something like Gatsby or Next.js if you work with javascript and react — I still think it is the most approachable option for beginners (like me).

To use a CMS or not?

I built a few starter websites with Jekyll. One of the things I missed at first was the integration with my writing tool of choice (Ulysses). I also wanted some of the benefits of a CMS, like scheduling posts. Ulysses integrates with WordPress and Ghost so you can publish from mobile and desktop. I decided to give Ghost a try.

As a CMS, I did love Ghost. It’s simple and focused on the writing experience. They have even embraced the Jamstack (Javascript, APIs, and markup) movement driving static websites and supporting headless designs. I also liked the idea of keeping my content separate from the frontend framework.

I worked with Ghost for a while but kept getting frustrated with the server upkeep that it invariable entailed. At first, I paid for a monthly subscription, but the functionality at the basic level is limited unless you spend $30/mo. At that level, you can either create your own theme to host with them or use their API to support a frontend framework built with Jekyll, Gatsby, or another tool. The cost is about the same as a good WordPress hosting provider, but that was more than I was willing to spend for the convenience of scheduling posts within a CMS.

I should note that Ghost also offers an option to self-host (starting at $5/mo through Digital Ocean) but I didn’t want to maintain the server myself. I already have enough reasons to not write without throwing in server updates…which were one of the reasons I wanted to leave WordPress.

Ultimately, I decided to forgo the CMS and focus on Jekyll. I’ll write more about this in the future, but Jekyll fits into my growing philosophy around working with markdown for personal knowledge management and publishing.

Publishing with Netlify

My first Jekyll website was published using Github pages. While I loved the option to publish a free project website directly from my repo, it was definitely more difficult to manage and came with a host of limitations.

Ultimately, I went with Netlify. They are a fantastic organization that makes it easy to build, deploy, and scale web projects. Using Jekyll, I can generate a website from my repo on Github and Netlify deploys it to edge servers across its network. Since I’m only serving static HTML files, this makes my websites incredibly fast for readers. And there is no server (on my end) to worry about securing, protecting, etc. Netlify handles the build and deploys the static files acrss the edge.

Getting set up

I won’t go into too much detail on the development process here, but I will link to the resources that I found the most helpful for getting started:

Poole: Clean and concise foundational setup for Jekyll
How to deploy Jekyll with Netlify
How to deploy Jekyll with GitHub pages
Formspree: Open-source form solution for static websites
Liquid template language reference from Shopify
Getting started with Netlify

As one of the original static website generators, Jekyll benefits from a large community of open-source contributors and users who have documented their techniques and solutions. If you get stuck, there is most likely a tutorial with the answers you need!

What’s next

Overall I’m pretty happy with the results of the project. I learned a lot along the way and ended up with a website that doesn’t look too bad and is unique to me. While I don’t need to make any changes to start writing, there are a few areas I plan to explore in the coming months:

Implement Tailwind CSS to replace Bulma I used the Bulma CSS Framework to scaffold the development of this project. Previously, I used Bootstrap for a few starter projects. Bulma is great, but I’ve been wanting something easier to customize. Enter Tailwind CSS, which is a just-in-time, atomic framework for creating CSS. I can build and design the website, all within HTML. Then, I can filter out any unused classes, resulting in a very small file.

Update 2024-12-01: I completed this work back in May 2022. I am currently using the excellent jekyll-tailwindcss plugin to implement Tailwind CSS for my site. I wraps the Tailwind CSS CLI and lets you specify which version of Tailwind CSS you want to use.

Buildout functionality for my digital garden I expect to write about this more in the coming months, but I’m planning to treat this blog more like a digital garden. There are some core functionalities I want to add, like sides notes, bi-directional links, and search, to make the reading experience more rich and interconnected.

Update 2024-12-01: I’m still working on this. Overall this feels a bit more like a distraction from writing than a priority. I have played around with introducing categories for evergreen, seedling, and budding notes to indicate how complete an idea/post is.

Rebuild the site with Gatsby, Next, or another framework I really like Jekyll, so this one isn’t urgent. But I’m starting to see how javascript frameworks like Gatsby, Next, or Vue could enable some new capabilities. One function that stands out to me is the ability to import markdown (my blog posts) from a separate Github repository. This way my thinking and writing could truly exist separately (and under version control!) from the frontend visual design.

Update 2024-12-01: I no longer plan to do this for a variety of reasons. I may write more about why in the future, but the short version for now is that I hate dependencies and heavy frameworks. I like how simple Jekyll is to run, and that the final result is really just a bunch of html files, one stylesheet, and one bit of non-critical, vanilla Javascript.

I hope you have a similar positive experience, and please reach out if you have any questions about building your website with Jekyll and Netlify.

Andrew Stiefel | coding

Building a personal monorepo for writing

Why use a monorepo?

Basic Setup

Configuring Obsidian

Connecting Jekyll and Obsidian

Publishing with Netlify

Final Workflow

Bonus: Convert Backlinks to Weblinks

Additional Resources

How I use GitHub as a CMS

Why?

Basic setup

Use issues to track posts

Writing and publishing posts

Final thoughts

Further Reading

Working with multiple GitHub accounts and SSH keys

Organize your local directory

Set your global gitconfig file

Create gitconfig files for each directory

Configure the SSH agent

Reset your local repositories

Resources

Build an email subscription form with Netlify Functions

The Challenge: Build a Mailing List Sign Up Form

The Team: Jekyll, Netlify, and ConvertKit

Create the serverless function

ConvertKit Subscription Form

Buttondown Subscription Form

SendStack Subscription Form

Create the email subscription form

Deploy the function

Conclusion

How to style an Atom feed with XSLT

Why Atom, and not RSS?

First, create the feed in Jekyll

Create the XSL file to style the feed

Conclusion

Additional Reading

How I built my blog with Jekyll and Netlify

Searching for something better

To use a CMS or not?

Publishing with Netlify

Getting set up

What’s next