My YAML tutorial in the context of Jekyll
Not many technical writers use YAML in their authoring tools. However, in the Jekyll environment, YAML is commonly used as an approach for creating a table of contents and other lists of content.
Most commonly, you store each item in your table of contents in a YAML file. You then iterate through that YAML file using Liquid syntax in order to push each item into a more complex HTML structure.
When I first learned that this is the approach to creating a table of contents in Jekyll, it struck me as odd. But as I have used it for a while now, I’ve found this is the best way to maintain a table of contents in Jekyll.
Just as JSON has become more popular than XML when it comes to formats for content, YAML (which is a superset of JSON) is also becoming a lot more popular than JSON as a configuration format. For example, a lot of times you configure an API service by passing it a YAML file that has a lot of settings.
YAML is more readable than JSON because it doesn’t have any tags. It just uses white space, and if you been reading Mark Baker’s recent post Why does XML suck?, you know that using whitespace as a way to format content can make things more readable. (By the way, that post from Mark is definitely one you’ll want to check out.)
Sponsored
I created a new tutorial on YAML and added it to my other tutorials that are in my Jekyll project. You can view my YAML tutorial here: YAML tutorial in the context of Jekyll
In my tutorial, I show a lot of examples of YAML and how to access the YAML data using Liquid and Jekyll.
Even if you aren’t using a static site generator, YAML could still be something that is useful to you in some way. Maybe you have a collection of items that you want to store, or maybe you want to hack in a table of contents into a system that doesn’t provide one, or maybe you have lists of related links. Learning how the YAML syntax works and how you can parse it to pull out items can be useful no matter what authoring tool you’re using.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, agent skills, tech comm careers, and more. Check out my AI courses for more on the latest in AI and tech comm. If you're looking for info about documenting APIs, see my API documentation course.
If you're a technical writer and want to keep on top of the latest trends in tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me.
Finally, I want to note a couple of things. I usually write the first drafts of my posts myself and then use AI to improve accuracy, clarity, and detail in places, so my writing is a mix of human and AI. (Hopefully that's not too off-putting.) Also, the opinions I express on my blog are my own perspectives, not those of my employer.