You may be familiar with style guides and design systems, and this is kind of like that. It’s my personal “Writing and Publishing System” that serves as a handy reference for me.
This guide is one of those cases where the content really only exists to help remove friction when I’m writing and forget all of the handy tools and elements I’ve built. It also helps me test and review things when I make stylistic adjustments to the site. (Otherwise, I’d have to browse through all of the articles and pages that use all of the elements and cover the spectrum of elements and their options.)
It’s public in case anybody else can benefit or apply any of the ideas to their own work, but it likely won’t be widely applicable outside of my quirky publishing setup.
Markdown & ERb
Most prose on the site originates as Markdown, but there’s a few areas where Markdown wasn’t robust enough. A thin layer of ERb and Rails helpers bridge the gap. This document provides the context about how to make the most of the available formatting approaches.
Figures & Figure References
Figures and figure references provide a unified way to reference visual elements and code samples in context so that the figure and the original reference location are connected by anchor references.
Figures & Figure References Guide
Visuals
Image-based figure elements for diagrams, photos, illustrations, screenshots, etc.
Code & Technical Content
Everything from large code samples with line numbers and highlights to inline code-adjacent values for variables, keyboard keys, and other related types of content.
Code & Technical Content Guide
Keyboard Keys & Shortcuts
Some super-handy ways to represent keystrokes and keyboard shortcut combinations with a simple helper that renders the resulting keys nicely-formatted.
Keyboard Keys & Shortcuts Guide
Sidenotes & Margin Notes
Like footnotes, but they live closer to their related content instead of being bolted on at the end. This way, folks don’t have to scroll all over the place to find a little bit of extra additional information.
Sidenotes & Margin Notes Guide
Callouts
Callouts can be used to draw attention to critical steps in a process or make note of a directly-related handy piece of advice or context that’s worthy of extra attention.
Quotations
Convenient ways to add quotations in consistent and semantically accurate ways. They could be inline, blockquotes, or even pull quotes.
Tables
Sometimes, you just need to display information in rows and columns. See how to use plain Markdown for tables or put them in a figure element.
Typographic & Semantic Bits
Examples of the full range of typographic elements that have been carefully integrated and tuned to create an ideal reading experience.
Typographic & Semantic Bits Guide
Lists
When you have lists of things and need them to look nice.
In addition to this guide, I’ve done my best to add comments throughout the source code of the site. So whether you like to use the good old-fashioned “View Source” approach or you’re more interested the server-side stuff on GitHub, it’s all there for anyone else to learn from.
And if you find it interesting or have questions or suggestions, I’m all ears and would love to hear from you.