From Bug Fix to Release Process Improvement: A Developer's Journey
How fixing a simple Vale configuration issue led to discovering and documenting critical improvements in our PyPI release workflow.
Welcome to Aditi
Aditi (short for āasciidoc dita integrationā) is a CLI tool designed to help technical writers prepare AsciiDoc files for migration to DITA. This blog chronicles the development journey, architectural decisions, and lessons learned along the way.
Recent Posts
Improving Aditi's Directory Selection UI: From Developer Jargon to User Clarity
How we transformed Aditi's confusing directory selection into an intuitive experience for technical writers
From VHS to YouTube: Converting Terminal Demos for Video Sharing
Created an automated script to convert VHS-generated GIFs into YouTube-compatible MP4 videos with optimal quality settings.
Implementing Journey Session Management for Seamless User Experience
Complete implementation of journey session management with pause/resume, backup system, and validation for interrupted workflows.
Fixing the Comment Flag Insertion Bug
Discovered and fixed a bug where comment flags were replacing content instead of being inserted above violations.
Improved Comment Flags with Dynamic Vale Data
Aditi now generates more informative comment flags using live Vale JSON output data.
Example Workflow
Visual walkthrough of Aditi's journey workflow
Introducing Aditi: AsciiDoc to DITA Migration Made Easy
A new CLI tool that automates AsciiDoc to DITA migration analysis and fixes, helping technical writers prepare documentation with confidence and speed.
CLAUDE.md Hybrid Automation System: Keeping Documentation in Perfect Sync
Implemented a comprehensive hybrid automation system that keeps CLAUDE.md synchronized with project state using templates, smart analysis, and multiple trigger mechanisms.
Fixing Jekyll Front Matter: How Inconsistent Blog Post Headers Broke GitHub Pages
Diagnosing and fixing Jekyll build failures caused by inconsistent front matter and template files with placeholder dates.
Complete AsciiDocDITA Rule Coverage Implemented
Implemented all 26 AsciiDocDITA rules with non-deterministic pattern for comprehensive DITA migration support.
Running Vale AsciiDocDITA Directly from Command Line
Learn how to bypass Aditi and run Vale with AsciiDocDITA styles directly using Podman/Docker containers for debugging and advanced workflows.
Removing Git Integration from Aditi CLI Design
Major design change: Aditi will provide high-level workflow guidance instead of prescriptive git commands.
Implementing Phase 1: Core Infrastructure for Aditi
Successfully completed Phase 1 of the Aditi project, building the core CLI infrastructure with modern Python packaging, configuration management, and comprehensive testing.
Implementing Vale AsciiDocDITA Integration: From Custom Container to Elegant Solution
Building elegant Vale AsciiDocDITA integration using containers - from custom solution to official Docker image.
Behind the Scenes: How Claude Code Organized Blog Assets from a Simple Request
A look at how Claude Code interpreted a request to organize screenshots and create a comparison blog post, demonstrating its file handling and content creation capabilities.
Jekyll Theme Comparison: Minima vs Just the Docs
Comparing Jekyll themes for the Aditi documentation site - evaluating Minima vs Just the Docs.
Setting Up GitHub Pages: Lessons from Configuring Aditi's Documentation Site
Step-by-step lessons learned while configuring GitHub Pages for the Aditi project documentation site.
I Finally Speak a Programming Language: My Journey into Vibecoding
How AI coding assistants transformed me from a non-programmer to someone who ships code daily, and why I'm starting over with Aditi.
Recent Commits
fix: Handle rules with no violations in journey workflow
- Mark rules as completed even when no violations are found - Display success message for rules already satisfied - Prevents infinite loop when all violations have been fixed
Also adds VS Code work...
Update recent commits data [skip ci]
chore: Bump version to 0.1.6 in pyproject.toml and __init__.py
test: Fix failing unit tests
- Update non-deterministic rule tests to include check field in Violations - Fix journey command tests by mocking questionary prompts and ConfigManager - Update journey workflow tests to properly m...
Update recent commits data [skip ci]
About Aditi
Aditi is a complete reboot of asciidoc-dita-toolkit, designed from the ground up with modern software architecture principles. The tool provides an interactive CLI experience that automates the detection and fixing of AsciiDocDITA rule violations.
Key Features
- Interactive CLI: Guided workflows for migration tasks
- Automated Fixes: Deterministic rule violations are fixed automatically
- Git Integration: Automated branch creation, commits, and pull requests
- Docker-based Vale: Consistent linting environment across platforms
- Comprehensive Reporting: Detailed violation reports and fix summaries
Get Started
(WIP - not yet available)
pip install --upgrade aditi
aditi journey
For more information, check out the design documentation or visit the GitHub repository.