A web journey: from HTML to Git-based Markdown workflows

Core premise: The evolution of web publishing is not a story of discarding old mistakes, but of progressive refinement. Each era solved a specific operational bottleneck—from initial manual control to CMS accessibility, structured scalability, static reliability, and ultimately the control and history of Git-based Markdown workflows.

My journey with the web spans over two decades, reflecting the evolution of publishing technologies and workflows. Here’s a technical look back at the tools, formats, and lessons learned.

Early days: HTML in Notepad and generators

Back in the late 20th century, my company tasked me with creating their first website. I learned HTML from scratch and wrote pages directly in Windows Notepad. Before moving to CMS-based approaches, I experimented with HTML generators such as Dreamweaver. While these tools allowed for visual editing, I quickly found them clumsy and difficult to use for tracking changes, especially when multiple versions or edits were involved.

The site was eventually published in a frames-based version, a common approach at the time despite usability limitations. Knowing the nitty-gritty details of HTML and HTTP requests laid the foundation for making informed technical decisions later: including using modern AI-assisted tools wisely to maximize performance and efficiency.

Enter CMS: SPIP and WordPress

For personal projects, I used SPIP to manage blog posts. Later, I built multiple sites (both personal and for non-profits) using WordPress. Its flexibility, plugin ecosystem, and ease of collaboration made it ideal for small teams or organizations with limited technical resources.

Structured content: DocBook and DITA

In professional settings, I shifted from general web pages to structured content. I first published DocBook content, then moved to DITA, using the DITA-OT toolkit to generate web output. Later, I used the Oxygen XML Editor to manage and publish structured content. Structured authoring separates content, presentation, and metadata, enabling more consistent, maintainable documentation.

The enduring contribution of DITA: The journey away from XML does not mean abandoning structured content. DITA trained writers in the mental discipline of information typing—isolating concepts, tasks, and references. For an in-depth exploration of keeping this model without the tooling bloat, see DITA XML to Markdown: lightweight information typing and strong information typing without the XML overhead.

Static site generators and lightweight markup languages

At another company, I published documentation websites using Python Sphinx, generating static HTML from reStructuredText sources.

Currently, at Unity, I use Markdown, edited either in Visual Studio Code or Emacs, which is then rendered into HTML pages. Moving away from CMSes, using version control systems such as Subversion and later Git was critical for managing changes, enabling collaboration, and maintaining a reliable history of content. This workflow emphasizes simplicity, version control, and maintainability while giving full control over the final output.

Version control is more than a transport pipe: Git is not merely a deployment mechanism. It provides an indelible audit trail, peer reviews via pull requests, branching for concurrent editorial projects, and instant rollback safety outside any proprietary database.

Modern web workflows: beyond CMS

When advising a non-profit considering a move from Drupal to a Symfony-based custom site, I recommended downgrading to WordPress to maximize collaboration. Later, a developer suggested a headless CMS approach with Astro + WordPress. I proposed going further: abandoning the CMS entirely and relying on Markdown + GitHub + Astro, a lightweight, modern, and fully controllable workflow. The case for managing content in plain files rather than databases lays out exactly why this choice pays off long-term.

Weighing the trade-offs: CMS vs. Git-based workflow

The transition from a CMS to Git-based files is not an absolute dogma—it is an architectural choice suited to team capabilities and operational needs:

Modern docs-as-code architecture

The current architecture delivers pure static HTML to the edge while keeping the authoring experience ergonomic and version-controlled:

Lessons learned from two decades of web publishing evolution

Looking back, my web journey mirrors broader shifts across the entire technical communications and web development landscape:

Takeaways for solo content developers and small teams

These principles are not theoretical abstractions—they are the distilled outcome of two decades of navigating publishing friction, platform churn, and refactoring:

Related reading

• Version management systems — rustic but reliable — the version-control backbone of this workflow.
• Git: from file to content — moving from files to managed content.
• Integrating documentation into development — docs inside the development workflow.
• DITA XML to Markdown: lightweight information typing — how information typing survived the shift from XML to plain text.
• Manage content in files, not databases — the architectural rationale for file-backed publishing.

External sources

• The static-site end state
• Sphinx/reStructuredText era of the journey
• Git as the workflow backbone