Get Info: #markdown

Automating the most annoying aspects of blogging

by Matt Sephton — Fri, 11 Oct 2024 16:42:00 +0000

Back in 2021 I had a look around and decided to base this incarnation of my blog on an open-source Jekyll theme called “Type”, though I’ve changed and added so much it’s quite some distance from the original as it stands today. As I added blog posts the performance became much worse. Initially I blamed Jekyll for this, until I took a closer look. What I learned was that the blog theme did some things in sub-optimal ways, so over the course of 2024 I have corrected as many of them as I can. Build time dropped from ~12 seconds to ~1 second.

My fixes and optimisations included:

Optimised SASS to compile once in plugin rather than header of every page (23 Feb)
Optimised all includes and templates to reduce build time (19 Aug)
Improved “noun” replacement, which are automatically-emphasised words (3 Sep)
Better YouTube embeds using lite-yt-embed (11 Sep)

And my additions along the way:

Multi-carousel support (14 Jul)
Automatic transformation of local images urls to CDN urls (19 Aug)
Automatic smart quotes in post titles (19 Aug)
Added OpenSearch to allow searching blog from address bar (15 Sep)

You might ask… what’s left to do? Not much I reckon. So I took a closer look at what is involved in me creating a blog post and made a list of the most repetitive, awkward or error prone tasks:

Entering links, partcularly links to other blog posts
Entering tags, going from memory or using search across project
Getting images onto my CDN server, currently copy by SFTP

Let’s solve all these annoyances!

Entering links and tags

You can read about these two in previous blog posts:

Created Markdown File Linker to make linking easier (8 Oct)
Created YAML Tag Picker to make tagging easier (8 Oct)

Getting images onto my CDN server

I was still having to copy my images to my CDN server manually, which was a pain. But the software stack on the server was intimidating. I kept putting it off for a rainy day, but I knew I would eventually get around to automating it.

The idea was to not upload the images at all, but rather download them to the server directly. I’d use a GitHub Webhook to trigger a git pull of the latest files onto my server. It took a few hours and a few attempts, but I finally arrived at a fairly elegant system I’m happy with:

GitHub Webhook that runs on push event
PHP script in web server docker container receives, validates, and creates a trigger file
Service on server outside of docker looks for trigger file and does git pull

Note: in January 2025, since this post was originally written, I have simplified the following files after migrating away from web servers in Docker containers to Caddy server. Highly recommended!

GitHub Webhook

Payload URL: https://www.example.com/webhook.php
Content type: application/json
SSL verification: enabled
Which events would you like to trigger this webhook: Just the push event
Active: on

Webhook receiver (PHP script)

Webhook git pull watcher (Shell script)

Trigger (System service)

Access control

Setup

You can set up the service using:

sudo systemctl daemon-reload
sudo systemctl start git-pull-watcher
sudo systemctl enable git-pull-watcher

Other commands

sudo systemctl restart git-pull-watcher
sudo systemctl status git-pull-watcher

Turning a Twitter Thread into a Blog Post

by Matt Sephton — Mon, 09 Jan 2023 00:00:00 +0000

Sometimes after posting to Twitter I’ll decide that I should really archive the information as a blog post. For single tweets that’s as easy (or difficult) as copying the text and images and publishing. For Twitter threads, it could be a lot more complicated. With a bit of lateral thinking I’ve found an easy way to do it.

Get the URL to a post in the thread
Unroll the thread using threadreaderapp.com
Open the web inspector
Highlight the element that contains the content (the one with data-controller="mentions")
Right click, and choose Copy > HTML
Paste the HTML into this Markdown converter
Copy the Markdown
Paste into your blogging system

The conversion from HTML to Markdown cleans or sanitises the content making for a straightforward paste into most blogging software.

Optional post-processing

You might want to repoint all embedded images from Twitter to locally-hosted copies
Some images in long threads might be lazy loaded, so you’ll need to fix those
Check and reinstate any embedded video iframes

Adding Markdown Support to Safari

by Matt Sephton — Fri, 25 Nov 2016 00:00:00 +0000

I recently created a Safari Extension that renders plain text Markdown files as good looking HTML right in your browser. I also added a context menu item so you can swap between the rendered HTML and the original Markdown text.

Download

gingerbeardman.com/safari/Doctor.safariextz (25Kb)

To install: double click the file after it has downloaded.

Why?

Recently my buddy and fellow Former Apple Technology Evangelist @TDRBY asked if there was an extension available for rendering Markdown files in Safari. I had a quick look—there wasn’t—and that got me thinking.

On macOS you can use Quick Look plugins to add support for new file types to Finder’s Quick Look preview popup. These plugins are great, I use a bunch of them, but they only apply in Finder and not in Safari. Maybe I could do something similar?

So, knowing that Safari renders plain text files by wrapping them in simple HTML > BODY > PRE markup, I thought that an extension should be able to modify such files. That was enough to pique my interest—so I got to work!

How?

The extension took less than an hour to put together. This blog post took me a lot more time to write! Anyway, here’s how I did it:

Create new extension using Safari > Develop > Extension Builder > + button
Set website access level to All
Confirm extensions run on plain text files in Safari by adding a CSS file containing only body { background-color: red !important; }—success, they do!
Find a suitable JavaScript Markdown to HTML converter showdown.js—this ticks two important boxes: it is easy to use, and is still being actively developed
Write a few lines of JavaScript to run showdown.js on the page text and replace it with the generated HTML
Add github-markdown.css and apply the markdown-body class to make things look better
Configure the extension to run only on URLs ending in common Markdown file extensions
Manually add https:// variations of the Markdown file extensions to the Info.plist (far quicker than using the Extension Builder user interface)
Edit the .map file reference out of the minimised showdown.js to avoid a runtime access warning
Build the release package

At this point I’d like to mention a couple of great open-source projects that made this task so much easier: github-markdown.css by Sindre Sorhus, and showdown.js by Estevão Soares dos Santos—nice work guys!

Testing

There are Markdown files all over the internet, but two notable source stand out.

Almost every GitHub project has a README.md file. View the RAW version to have the extension render it as HTML. Here’s the one I used for testing.
John Gruber’s excellent daringfireball.net blog is written using Markdown, and the source of each post can be seen by appending .text to the URL. Here are two posts that I used to test. Of course, John is also the creator of Markdown. Thanks, John! 👍

Postmortem

After the initial build, a period of testing revealed some issues:

Strikethrough, and some other non-standard but frequently used Markdown, was not being rendered. This was fixed by enabling some options in the showdown.js file.
Rendering quirks due to using github-markdown.css outside of the GitHub page structure required few manual CSS tweaks. Mainly this was to make tables look better.
Markdown on GitHub that was already rendered as HTML was being processed a second time, resulting in corrupted pages. This was fixed by blacklisting the github.com domain.
Sometimes I wanted to see the plain text Markdown. I fixed this by spending an inordinate amount of time adding a context menu item that allows you to Show or Render Markdown. I hope it was worth it! 😬

Safari Wish List

Despite the brief development, I noticed a few quirks to do with Safari that I did not expect to encounter:

You can’t open the Web Inspector whilst viewing a plain text file. But if you open the inspector on a blank tab, or an existing HTML page, you can then navigate to the plain text file and the inspector will remain open. Phew!
Due to the way Safari Extension access permissions work, I have had to enable the extension for all pages and then reduce its power by whitelisting a range of Markdown file extensions. This feels like cracking a nut with a sledgehammer.
Extensions do not run on local file:/// documents. 😩

Please join me in filing enhancement requests with Apple if you’d like to add your support to any of the above points.

Thanks for reading!

If you have any questions feel free to get in touch using twitter or my website. I’m interested to see more extensions that add support for other file formats in Safari. And I’m available to help you make better products!