Serving Markdown for AI Agents, Now as a Jekyll Plugin

# What happened

The author turned a one-off script that produced Markdown versions of blog posts into jekyll-md, a proper Jekyll plugin. The original setup had a script (_scripts/render_markdown.rb) wired into a GitHub Actions deploy workflow because GitHub Pages' native build only allows a small plugin allowlist. jekyll-md moves that conversion into the Jekyll build itself.

# What jekyll-md does

jekyll-md converts a page's fully rendered HTML output into Markdown and adds a discovery tag at the same URL. That lets automated consumers fetch clean Markdown instead of scraping HTML.

By default the plugin looks for or [role="main"] and falls back to the full. You can override that with a CSS selector, for example:

• Gemfile: gem 'jekyll-md'
• _config.yml: plugins: - jekyll-md

The README contains the full configuration options, including the selector setting (e.g. md: selector: "#markdown-content").

# Why the author did this

The original approach was functional and even generated $360 in referral conversions after an AI agent apparently read the clean Markdown version of a post. But it required extra scripting and per-page Liquid front matter. Moving to a plugin centralizes the logic, removes per-page configuration, and integrates with Jekyll's hooks and generator system.

# The llms.txt decision

There is a related convention, llms.txt, which is meant to provide a small, curated map of a site for agents. The author considered adding automatic llms.txt generation to jekyll-md but chose not to. The reasoning: a plugin that walks every page and dumps them into a single file recreates the sitemap problem — too large and unfiltered for useful context. Instead, the author hand-writes llms.txt as a Jekyll page with Liquid front matter that lists:

• pinned posts (using the blog's existing pinned: true flag)
• the 10 most recent posts
• a few key pages

That curated file is available at code.dblock.org/llms.txt, and the template that generates it is published alongside the blog.

# Practical notes for implementation

• Installation: add jekyll-md to your Gemfile and _config.yml as shown above.

• Customization: set a CSS selector in the plugin config to narrow the conversion target.

# Where to look next

The author published the jekyll-md gem and linked to the original "Serving Markdown for AI Agents" post and a GitHub Actions workflow used previously to deploy and serve Markdown. The blog also contains the llms.txt template used to produce a curated instruction file.