Everything this site can do to an article

I love building powerful, flexible, extensible systems. I love it so much that I procrastinated writing posts for this site by overbuilding the publishing system itself.

This post is part show-and-tell, part reference doc for me while I maintain the site and write new articles.

I’ve always admired docs that are also the product — it’s always tickled me that man man is the canonical way to learn about man pages, or that Python’s doctest runs the docs’ examples to ensure they stay true through code changes. This post is my take on that idea: every feature of articles on this site will be demonstrated in this post. I even have an agent instruction to ensure that new features added to the site manifest themselves somewhere on this page!

I hope this gives you, dear reader, something approaching entertaining to read while I remember how to invoke a particular feature. Win-win!

If you can dream it, you can do it.

- NOT Walt Disney

No, that isn’t really a Walt Disney quote. But it is an example of a Markdown blockquote! All manner of Markdown features are supported here, including…

…Headings! (and other Markdown quality-of-life)#

Well, including that ^. In addition to Astro’s unified-based remark and rehype pipeline, I’ve made some custom plugins to do things like automatically give headings stable IDs and apply permalink anchors.

The link above to the Carousel of Progress ridethrough will always open in a new tab thanks to another one of those custom plugins. Internal links, like one to this project, ryanhecht.com, are styled differently, and if you hover over it, you’ll get a preview of the artifact you’re about to visit. Sometimes, I’ll want to link to a post I haven’t written yet — partially to denote “there’s more to this story I’d like to tell some day” and guage interest from readers, and partially as a public TODO list I’ll be accountable to! I call these stories for another time, and they’re styled uniquely as well.

A nice quality of life feature for me is that I use exactly the same Markdown syntax for internal and external links:

External links and internal links are styled differently, but I use the same Markdown syntax for both:

[Well, including that ^](https://www.youtube.com/watch?v=ZuISom1ANwg&t=3681).

[ryanhecht.com](/projects/ryanhecht-com/)

And would you look at that, a code block! Yet another custom plugin extends Astro’s Shiki syntax to add an optional filename bar, line highlighting, and a copy button that says whether it worked — out loud for screen readers, and with a fallback key hint for the browsers that refuse clipboard access.

Preceding the Prose: Frontmatter#

Markdown frontmatter lets me define all the meta-info about this article. You’ve got your basics, like title/description/publication date, but also nifty inclusions like “TL;DR” bullets, tags for grouping similar articles together, and a project field that links this article to a project page without me having to edit the project page itself. I’ve also built in support for article series, should I ever endeavor to write a multi-part thriller.

The entire frontmatter for this article is reproduced below:

---
title: Everything this site can do to an article
description: A working article that demonstrates the features of this Astro-based publication system. Part show-and-tell, part reference doc.
tldr:
  - This page is both documentation and a working specimen of the article system.
  - Every reader-facing article feature should appear here in the form a real post would use it.
  - When the publication gains another relevant capability, this page will change!
published: 2026-08-05
updated: 2026-09-03
lastReviewed: 2026-09-03
updateNote: A brief note about what was updated
tags:
  - publishing
  - design
  - Astro
project: ryanhecht-com
draft: false
preview: false
accents:
  - "#f5a649"
  - "#cae9f5"
series:
  slug: how-this-publication-works
  title: How this publication works
  order: 1
---

Structure becomes navigation#

Remember those Markdown heading stable IDs we mentioned earlier? They drive the table of contents on your left (on desktop) that scrolls with you as you read. The design is inspired by Wikipedia’s current table of contents implementation.

I got a lot of inspiration for this system from various blogs/personal websites out there. My initial prompt to the Copilot CLI was to grab every personal blog and news site posted to Hacker News in the last 30 days and raise any interesting design patterns, features, or things that matched my goals for this website as I dictated them!

A subsection#

Just wanted to show that I support subsections, too!

This isn’t in the table of contents#

It’s just ## and ### headings that get stable ID’s and a table of contents entry. #### and beyond are just for visual hierarchy At least for nowAt least for now#Of course, I might change my mind in the future and give #### headings their own TOC entries.

Oh, by the way, this is a Sidenote, another custom MDX component I made! I tend to tangent a lot, write a lot of parentheticals, and otherwise dart off in sometimes substantial diections. The sidenote helps me do that without breaking the narrative flow!

Where you found this note depends on how wide your window is. Past about 1200px there is a margin to put it in, so it is already sitting out there beside the paragraph that raised it, and you can ignore it or not without doing anything. Narrower than that there is no margin to spare, so the numbered marker becomes a real control: press it and the note unfolds here in the column, press it again — or the ✕ in its corner, or Escape — and it folds back up. Tangents should be optional..

That’s it!#

This page will be ever-evolving as I no doubt add more features to the publishing system (likely more frequently than I write new content).