Diataxis

Diataxis is a command-line tool for managing documentation following the Diataxis framework. It supports 9 document types — how-to guides, tutorials, explanations, ADRs, notes, handovers, 5-why analyses, project briefs, and PR summaries — with automatic README integration.

Features

• Create and manage 9 document types via a simple registry DSL
• How-to guides with automatic "How to" title normalization
• ADRs with auto-numbered sequential filenames
• Tutorials, explanations, notes, handovers, 5-why analyses, project briefs, and PR summaries
• Automatically update README.md with links to all documentation
• Recursive document discovery in subdirectories
• Configurable directory structure via .diataxis config file
• DIATAXIS_ROOT environment variable for running dia from any directory
• --tag/-t flags and DIATAXIS_TAGS for attaching YAML front matter tags at creation time
• --stdout to print a template to standard output instead of writing a file
• Shared metadata guidelines injected into templates via {{common.metadata}}
• Maintains alphabetical order in documentation lists

Installation

Install the gem by executing:

git clone https://github.com/gavindidrichsen/diataxis.git
cd diataxis
gem build diataxis.gemspec
gem install diataxis

Make sure that dia is available on your PATH.

Usage

# initialize a new diataxis project (creates .diataxis config)
dia init
cat .diataxis                                           # view and edit the default configuration

# Create documents — all 9 types supported
dia howto new "How to configure SSL certificates"       # how-to guide (auto "How to" prefix)
dia howto new "Configure SSL certificates"              # imperative form also works
dia tutorial new "Getting Started with Docker"          # tutorial
dia explanation new "Why We Use PostgreSQL"             # explanation
dia adr new "Do whiteboard wednesday talks"             # ADR (auto-numbered)
dia note new "Meeting Notes Q4"                         # note
dia handover new "Frontend Ownership"                   # handover
dia 5why new "Login Timeout Root Cause"                 # 5-why analysis
dia project new "API Migration"                         # project brief
dia pr new "Refactor Auth Module"                       # PR summary

If you change any document titles, then run the following to automatically rename the filenames and update the links:

dia update .

Environment Variables

Set DIATAXIS_ROOT to run dia commands from any directory without cd-ing to the project root:

export DIATAXIS_ROOT=/path/to/my/project
dia explanation new "Why We Chose PostgreSQL"           # creates doc under DIATAXIS_ROOT
dia update                                              # updates README at DIATAXIS_ROOT

When DIATAXIS_ROOT is set, all operations — init, document creation, and update — target that directory and load the .diataxis config from there.

Tagging Documents

Attach tags to generated documents as YAML front matter using --tag/-t flags or the DIATAXIS_TAGS environment variable:

# CLI flags (repeatable)
dia explanation new "API Design" --tag backend -t api

# Environment variable (comma-separated)
export DIATAXIS_TAGS="sprint-42, backend"
dia howto new "Configure Redis"                         # inherits tags from DIATAXIS_TAGS

# Both sources are merged and deduplicated
DIATAXIS_TAGS="backend" dia note new "Redis Notes" -t api
# Result front matter: tags: [backend, api]

Tags are prepended as YAML front matter at the top of the generated document:

---
tags:
  - backend
  - api
---

When no tags are specified, no front matter is added — existing behaviour is unchanged.

Printing to stdout

Add --stdout to any document command to print the rendered template to standard output instead of writing a file. This is useful for piping a fresh template into another tool — for example, injecting it into an AI discussion:

dia explanation new "How to fly" --stdout            # prints the template, creates nothing
dia adr new "Use PostgreSQL" --stdout                # ADR number/status still injected
dia howto new "Configure Redis" --stdout --tag backend

--stdout has no filesystem side effects: it needs no .diataxis config, creates no directories, writes no file, and leaves README.md untouched. Type-specific behaviour (how-to title normalization, ADR numbering, tag front matter) is preserved.

For more information including design decisions and how-to's see docs/README.md.

Testing

This project uses:

• RSpec for unit testing
• Cucumber with Aruba for BDD/CLI integration testing

For detailed information on using Cucumber with Aruba, see Cucumber & Aruba Cheatsheet.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Acknowledgments

The ADR functionality in this tool is inspired by and maintains compatibility with two excellent projects:

• adr-tools - The original ADR management tool that established many of the conventions we follow
• adr-log - A complementary tool for generating ADR logs

Like these tools, our ADR implementation:

• Uses the standard ADR format (Context, Decision, Consequences)
• Maintains a chronological sequence of decisions
• Supports superseding and amending previous decisions
• Generates consistent, numbered filenames
• Preserves markdown formatting

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/gavindidrichsen/diataxis. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Diataxis project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Appendix

Design Decisions

• ADR-0001 - Adopt Diataxis Documentation Framework
• ADR-0002 - Use Configuration File for Document Paths
• ADR-0003 - Auto-Generate README with Document Links
• ADR-0004 - Use Linguistic Prefixes for Document Classification
• ADR-0005 - Use Purpose-Driven Document Templates
• ADR-0006 - Implement Automated README Link Management
• ADR-0007 - Enable Recursive Document Discovery
• ADR-0008 - Refactor document templates into separate class files for improved maintainability
• ADR-0009 - Hide README sections when no matching documents exist
• ADR-0010 - Implement Custom Error Handling System
• ADR-0011 - Implement centralized logging system with Ruby Logger
• ADR-0012 - Move to External Template System with Direct TemplateLoader Usage
• ADR-0013 - Set default directory for all templates
• ADR-0014 - Underscore the gtd directory for project files so they always live at the top
• ADR-0015 - Support environment variable configuration with DIATAXIS_ROOT and DIATAXIS_TAGS
• ADR-0016 - Replace per-type class files with registry DSL and template method hooks
• ADR-0017 - Obsidian, not GitHub, is now the primary reading surface