DocOps Lab

Bridging the gap between document professionals and the world of code.

DocOps Lab is working to distribute the power of docs-as-code for non-programmers.

They know their content inside and out, but they are locked out of the advanced workflows that developers take for granted: powerful automation, robust single sourcing, and collaborative editing and version control using Git.

The Bridge

Through several interconnected open source projects, DocOps Lab is creating pathways for “tech-savvy non-programmers” to harness developer tools.

DocOps Box: 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: 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: 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: 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 Extensions: 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.
Issuer and ReleaseHx: 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, or HTML formats at release time.

The goal of all this is to create a “docs-as-code” ecosystem that empowers developers and non-developers alike to leverage the full power of modern documentation practices without needing to become full-fledged developers.

See the website sourced in this repo for the best overview of DocOps Lab and its projects: docopslab.org.

This Repository

This codebase (DocOps/lab) contains the Jekyll-based website for DocOps Lab, served at docopslab.org.

It also contains assets that are common across multiple DocOps Lab projects. That includes documentation, which is part of the docopslab.org site (see _docs/). It also includes the docopslab-dev Ruby gem, which is used for running common development and quality-assurance (QA) tasks (see gems/docopslab-dev/).

Generated Artifacts

Aside from the docopslab.org website, which will take up most of this README, this repository also generates:

a Vale styles package (DocOpsLabStyles.zip) that incorporates custom styles and upstream packages
the docopslab-dev Ruby gem package
the docopslab/dev Docker image
the agent/docs/ library of Markdown files generated from AsciiDoc sources

The Site

The site has a landing page which leads mainly to a showcasing of DocOps Lab projects with a modern, professional interface featuring project cards, dependency visualization, and custom DocOps-themed icons.

It also includes technical documentation that is common across projects, as well as a blog for updates and topical writings.

Blog Versioning

This site hosts two blogs: the DocOps Lab Blog and the DocOps Lab MetaBlog.

Each blog post tracks its own version in the :page-version: attribute. The version follows Semantic Versioning, with a MAJOR.MINOR.PATCH structure.

A version bump is required whenever the rendered content of the post changes, whether through direct edits to the post file or through modifications to any AsciiDoc includes used by that post, if those changes affect the post content.

Includes do not carry their own versions; the post’s version is the sole authority. Version numbers should change even for small mechanical edits so that the version always reflects the current state of the published text.

MAJOR: Substantial reframing or rewriting. Prior understanding may no longer apply.
MINOR: Additive content or clarifications that do not contradict earlier versions.
PATCH: Typos, grammar cleanup, mechanical style adjustments, or any small textual edits.

Mere changes of style or layout do not cause version bumps.

Repository Structure

This repository uses a dual-branch deployment for GitHub Pages publishing.

We’ll talk about major source/output branches, then explore the deployment flow and broader ecosystem.

Main Branch (`main`)

Contains all source files:

Jekyll source files (_layouts/, _includes/, _sass/, etc.)
Content collections (_blog/, _docs/, _projects/)
Project data (_data/docops-lab-projects.yml)
Configuration files (_config.yml, Gemfile)
Build automation (Rakefile)
Slides content (slides/)
Jekyll plugins (_plugins/)
Site assets (SCSS, JS, images)
Common task scripts (scripts/)
Ruby-based ops tooling and libraries as sub-projects (gems/)
Specification and definition files (specs/, for this repo)

GitHub Pages Branch (`gh-pages`)

Contains only the built website files:

Static HTML, CSS, JS files (from Jekyll build output)
Preserved slides/ directory with existing presentation content
Minimal .gitignore for deployment scope

Artifact Deployment

Non-website artifacts are published via other means.

Vale styles package (DocOpsLabStyles.zip): GitHub repo assets
docopslab-dev Ruby gem: Rubygems.org
docopslab/dev Docker image: Docker Hub
Agent docs library: agent/docs/ on agent-docs branch

DocOps Lab Docs Sites

Most DocOps Lab projects have their own documentation sites, also built with Jekyll and AsciiDoc, often including YARD for Ruby API reference generation.

For less-formalized projects, documentation is restricted to README.adoc and other *.adoc files. These are hosted as GitHub Pages sites from their respective repositories, but using a consistent URL structure centered on the docopslab.org domain hosted here.

The URL structure is as follows:

Project landing page: https://<project>.docopslab.org/

At a minimum, this should be a subset of the README.adoc file.
Product user docs: https://<project>.docopslab.org/docs/
Product developer docs: https://.docopslab.org/docs/api/(/)

The final <apiname> directory is only applicable when the product contains multiple distinct APIs.

GH Pages configuration for these sites enables deployment by way of a clean gh-pages branch containing only generated documentation artifacts and the CNAME file.

Development Workflow

This site is not open for unsolicited content contributions, but if you want to propose a bugfix (including a content correction), either:

use the issues system and post about it
fork the repository and issue a pull request.

Prerequisites

Ruby 3.x
Bundler: gem install bundler
Ruby dependencies: bundle install

Or just use the docopslab/dev Docker image, which has everything pre-installed.

See Devtool Setup for details.

Local Development

Start development server with live reload

bundle exec rake serve

Serve at a specific port (default is 4000)

PORT=4100 bundle exec rake serve

Build the site without serving

bundle exec rake build_site

Wipe and rebuild artifacts

bundle exec rake clean

Deployment Workflow

The repository includes a comprehensive Rake-based deployment system:

Safe Testing (Recommended)

Prepare deployment files (no commit/push)
```
bundle exec rake deploy_safe
```
Review changes on gh-pages branch
```
git status
ls -la
```
Commit when satisfied
```
bundle exec rake commit_deploy
```
Push to live site (with confirmation prompt)
```
bundle exec rake push_deploy
```
Return to main branch
```
bundle exec rake return_to_main
```

Full Deployment

One-command deployment (prepare + commit + push)

bundle exec rake deploy

Slides Management

These slides are from a hastily posted presentation before the DocOps/lab site was really built. This is a legacy placeholder for content that will likely move to Docs-as-Code School eventually.

Update slides from docs-as-code-school repo

bundle exec rake update_slides

Deploy with slides update

bundle exec rake deploy_with_slides

Building the `docopslab-dev` Gem

The docopslab-dev gem is developed within this monorepo at gems/docopslab-dev/.

There are several Rake tasks devoted to managing this sub-project and its artifacts, all under the gemdo: task namespace.

bundle exec rake -T | grep gemdo:

Generate the docopslab-dev gem

bundle exec rake gemdo:build_gem

Agent Documentation Generation

Before building the gem, agent documentation must be generated from AsciiDoc sources:

Generate agent documentation

bundle exec rake gemdo:generate_agent_docs

This task performs the following:

Builds the Jekyll site (if not already built)
Converts _docs/agent/*.adoc → HTML → Markdown
Processes _docs/templates/AGENTS.markdown (strips Jekyll frontmatter)
Writes all generated docs to gems/docopslab-dev/docs/
- docs/agent/AGENTS.md - Template for target projects
- docs/agent/*.md - Agent instruction guides

Note	Generated documentation files are git-ignored as they are built artifacts. They are packaged with the gem during the build process.

Full `devlab:` Rake Testing

Test all the docopslab-dev gem’s Rake tasks in sequence:

bundle exec rake gemdo:test_tasks

Test specific tasks with:

bundle exec rake 'gemdo:test_tasks[spellcheck:file,help]'

Gem Build Process

Build the gem; includes pre-build

bundle exec rake gemdo:build_gem

Built gems are placed in gems/docopslab-dev/pkg/.

Use bundle exec rake to invoke the docopslab-dev library.

Docker Image Build

Build the docopslab/dev Docker image

bundle exec rake gemdo:build_docker

This builds a complete development environment with all tools pre-installed.

Workflow Steps

When working on the gem:

Make changes to gem source files in gems/docopslab-dev/.
Make changes to agent docs in _docs/agent/ or _docs/templates/.

Generate updated documentation.

bundle exec rake gemdo:generate_agent_docs

Build and the gem.
```
bundle exec rake gemdo:build_gem
```
Test in a target project.
1. Ensure project Gemfile or .gemspec sources gem as relative path.
  'docopslab-dev', path: '../lab/gems/docopslab-dev'
2. Use Bundler to invoke the gem’s Rake tasks.
  bundle exec rake labdev:check

For more details on using the gem in target projects, see gems/docopslab-dev/README.adoc.

Vale Style Development

To add or modify DocOps Lab custom styles for Vale:

Alter styles at source in gems/docopslab-dev/assets/config-packs/vale/.

Sync changes to project Vale config.

bundle exec rake labdev:sync:styles:local

Test with Vale linting.
```
bundle exec rake labdev:lint:docs | grep 'Package.RuleName'
```
Where Package.RuleName is the name of the custom rule you’re working on.

See Vale’s Style documentation for details on creating and modifying Vale styles.

Addressing Issues Revealed by Linters

Identify and fix spelling issues

Use Vale to identify spelling issues

bundle exec rake labdev:lint:spellcheck

Use the generated report to guide your fixes. See complete docs at Fix Spelling Issues.

Identify and fix RuboCop offenses

bundle exec rake labdev:heal:ruby

Unfortunately, for offenses that cannot be fixed automatically, you’ll need to consult the DocOps Lab Ruby Style Guide and RuboCop documentation.

Site Features

Project Showcase

Vertical project profiles with hover-to-expand descriptions
Custom DocOps icons integrated with Lucide icon system
Dependency visualization with hover popovers
Project filtering by type and development wave

Technical Implementation

Jekyll 4.3.4 with AsciiDoc support
SCSS/CSS custom properties for theming
Responsive design with 70% max-width layout
Custom Lucide icon integration via JavaScript
YAML-driven content from _data/docops-lab-projects.yml

Jekyll/AsciiDoc

The lab site uses Jekyll 4 with AsciiDoc support via the jekyll-asciidoc plugin. It does not yet use the jekyll-asciidoc-ui or jekyll-asciidoc-ext plugins, which are still on the DocOps Lab roadmap.

This site is intentionally a relatively bare-bones Jekyll-AsciiDoc implementation with NO CUSTOM FILTERS and NO CUSTOM TAGS and most Jekyll framework conventions/defaults maintained.

It does, however, add a module for XrefAttrs, which is a candidate module for jekyll-asciidoc-ext.

It also has front-end customization, again independent of jekyll-asciidoc-ui.

Custom Plugin: `xref_attributes`

This plugin makes AsciiDoc cross-references available as AsciiDoc attributes when AsciiDoc files are converted.

The format is {xref_<collection-label>_<page-slug>_url} and {xref_<collection-label>_<page-slug>_title}.

For example: {xref_docs_infrastructure_url} to render /docs/infrastructure/.

Use {xref_<collection-label>_<page-slug>_link} as a shortcode for the entire link element.

Pages

Page Path	Description
`/`	Landing page with starred projects
`/projects/`	All projects listing
`/docs/`	Documentation
`/blog/`	Main DocOpsLab Blog posts
`/metablog/`	Blog posts about the blog

Data Structure

The site is driven by _data/docops-lab-projects.yml, which contains:

Project definitions with metadata, descriptions, dependencies
Type classifications (content, environment, framework, etc.)
Development waves with release timelines
Custom icon assignments for DocOps-specific projects

Icon System

The site uses a hybrid icon approach:

Standard icons: Lucide icons via CDN
Custom icons: SVG definitions for DocOps-specific concepts

Domain Configuration

Production	https://docopslab.org
GitHub Pages	Served from `gh-pages` branch
CNAME	Configured in repository settings
GH Alias	https://docopslab.github.io/lab

Contributing

Contributions to this repository are welcome, but in this case especially, it makes sense to be in touch or involved with DocOps Lab before offering significant changes or additions.

Making Changes

The current one-contributor workflow is as follows:

Work on a main branch.
Edit source files in _layouts/, _includes/, _sass/, etc.
Update project data in _data/docops-lab-projects.yml.
Test locally with rake serve.
Deploy with rake deploy_safe → review → rake commit_deploy → rake push_deploy.

This workflow will change once other organization members are actively working on the lab repository.

Registering Projects

Edit _data/docops-lab-projects.yml:

## New Project:
  - name: Project Name
    type: framework  # see $meta.types for options
    desc: |
      Project description
    deps: [dependency1, dependency2]
    done: 80%; v1.0
    wave: 2
    icon: lucide-icon-name  # or custom icon

Custom Icons

Add new custom icons in _layouts/default.html:

// Register custom icon
lucide.createIcons({
  icons: {
    'new-icon': lucide.createElement('svg', {
      // SVG attributes and paths
    })
  }
});

Troubleshooting

Build Issues

Ensure Ruby version matches .ruby-version
Run bundle install to update dependencies

Deployment Issues

Verify you’re on main branch with no uncommitted changes
Check that gh-pages branch exists

Icon Issues

Custom icons must be registered in _layouts/default.html
Verify icon names match between YAML data and JavaScript registration
Check browser Inspector panel’s console tab for JavaScript errors

Licensing

All original textual content is released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license. Content includes anything sourced under _docs/, _blog/, _metablog/, and _data/.

Images, including original graphics, are either copyleft or published under Fair Use and attributed to their best-known source.

All code is released under the MIT License. Code includes .rb, .sh, .js, .html, and other non-content files.

Support

For issues or questions about this website implementation, contact the DocOps Lab team or create an issue in this repository.

docopslab-dev

Runtime