Much of this website consists of representations of DocOps Lab projects, in different orders and forms.
Project metadata is stored in the _data/docops-lab-projects.yml file, which is the canonical source of truth about the numerous codebases DocOps Lab maintains.
At least, it represents the sole source of most of the data it contains, though at any given point some part of that file is likely out of sync with reality.
Nevertheless, some aspects of this sourcing and output strategy are pretty extreme and therefore worth blogging about.
Source Files
Effectively all of the information about DocOps Lab projects on this site is single-sourced, though some of it is sourced (once) in different places.
Most of it is sourced in the docops-lab-projects.yml file, which we will dive into shortly.
|
The content of the code snippets used in this post is subject to change. When the blog next builds, the live data will be transcluded into the code blocks on this page, and the text around them should remain accurate. |
A small amount is sourced in the README.adoc file, as data attributes.
This includes the text for each of the Featured Projects cards on the landing page, which are also expressed in the README file itself.
README.adoc:docops-box-desc: A Docker-containerized environment and shell script for reducing the complexity of setting up “developer tools”. Non-developers can run a single command (`docksh run`) and instantly access whole runtimes and specialized documentation tools in a pre-configured shell environment.
:docs-as-code-school-desc: Structured education in modern technical documentation and document processing. Starting with “Deep Semantics” (Fall 2025?) and expanding to courses on version management, code-like workflow adoption, and legal document operations, this project uses docs-as-code to teach docs-as-code principles.
:ayl-docstack-desc: AsciiDoc. YAML. Liquid. A three-language approach to managing complex, multi-variant documentation. This “tech stack” maximizes power while minimizing syntax overhead, making advanced documentation techniques accessible to beginners while remaining powerful enough for enterprise needs.
:schemagraphy-desc: Extends YAML through SGYML and accompanying libraries, providing advanced data typing and document transclusion capabilities. Provides a full-featured schema language that allows users to define complex data structures, document structures, and whole interfaces in a single, unified format.
:jekyll-asciidoc-ui-desc: A set of Jekyll plugins and themes that enrich AsciiDoc web output. Includes themes like AsciiDocsy and Just The AsciiDocs, plus plugins for Jekyll-OpenAPI integration, adocBook document converter, and 25 UI extensions for AsciiDoc.Data Structure
The docops-lab-projects.yml file is basically a large array of tabular data.
Each project’s record has a number of parameters.
- name: DocOps Box
slug: docops-box
type: environment
desc: |
Everything needed for managing customized Ruby, Node.js, Python, and Pandoc environments via Docker containers, ready for interactive work.
Including the popular ZShell with handy configurations.
Alternatively builds a production-ready ("live") image for automation/deployment.
line: Up and running with Ruby, Node, Zsh, Pandoc, and Git for document operations with interactive and production-ready Docker images.
star: true
page: true
done: 90%
vrsn: 0.1.0
wave: 0
card: readme
icon: container
tech: [Docker,Bash,Zsh,Ruby,Git,Pandoc,Node.js,Python]
tags: [development,automation,containers,virtualization,Dockerized]
sort: 1I think most of the above data record is mostly self-explanatory, but a few fields merit highlighting.
I also added a concept of custom cards, which are defined in another file: _data/cards.yml.
As of now, it contains only one card record.
- name: Issuer and ReleaseHx
type: utility
card: |
Issue-ticket creation and release-history management tools that integrate with Jira, GitHub, and GitLab. Bulk-create work items from a single YAML file, then generate release notes and changelogs in AsciiDoc, Markdown, YAML, JSON, HTML, or PDF formats at release time.
icon: logs
sort: 6
href: /blog/issuer-releasehx-news/This is all pulled together using simple Liquid assignments and filters.
{% assign starred_projects = site.data.docops-lab-projects.projects | where: 'star', true %}
{% assign featured_projects = starred_projects | concat: site.data.cards | sort: 'sort' %}Project Profiles
Project profiles come in micro, mini, and page sizes.
The micros are for card-based representations, such as the Featured Projects section on the landing page, or pages that group projects in ways that might involve repeated instances of the same project in the output, such as the Projects by Technology and Projects by Category pages.
The minis are for the project detail sections that appear on the Projects Overview page, which includes a lot more information about each project, but still in a compact format.
Finally, some projects have their own dedicated pages, such as Docs-as-Code School. This is the most comprehensive representation of a project.
I can even re-create one here in this page using Liquid templates.
DocOps Box
0.1.0Up and running with Ruby, Node, Zsh, Pandoc, and Git for document operations with interactive and production-ready Docker images.
A Docker-containerized environment and shell script for reducing the complexity of setting up “developer tools”. Non-developers can run a single command (docksh run) and instantly access whole runtimes and specialized documentation tools in a pre-configured shell environment.
The above “mini-profile” expression was called with this Liquid code:
{% include project-profile.html slug='docops-box' %}Note how the style for this page remains largely intact in affecting the profile rendering.