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

<blockquote class="border-l-4 border-indigo-500 pl-4 py-2 my-6 bg-indigo-50/50 dark:bg-indigo-950/20 text-indigo-950 dark:text-indigo-200">
**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.
</blockquote>

<div class="my-6">

</div>

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.

## Enter CMS: SPIP and WordPress

For personal projects, I used **[SPIP](https://www.spip.net/en_rubrique25.html)** 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.

<div class="my-6">
  <ConceptCard title="Phase 2 · 2000s: Content Management Systems" badge="Collaboration">
    <dl class="grid sm:grid-cols-3 gap-3 text-xs sm:text-sm m-0">
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Tooling</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">SPIP, WordPress, MySQL, PHP themes & plugins</dd>
      </div>
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Problem Addressed</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">Lowering the barrier for non-technical authors; handling multi-author publishing</dd>
      </div>
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Lesson Learned</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">CMSes enable teamwork, but store content in databases that hide granular change history</dd>
      </div>
    </dl>
  </ConceptCard>
</div>

---

## 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](https://www.oxygenxml.com/)** to manage and publish structured content. Structured authoring separates content, presentation, and metadata, enabling more consistent, maintainable documentation.

<blockquote class="border-l-4 border-blue-500 pl-4 py-2 my-6 bg-blue-50/50 dark:bg-slate-800/60 text-slate-900 dark:text-slate-100">
**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](https://redaction-technique.org/dita-xml-to-markdown-lightweight-information-typing) and [strong information typing without the XML overhead](https://redaction-technique.org/strong-information-typing-without-xml-overhead).
</blockquote>

<div class="my-6">
  <ConceptCard title="Phase 3 · 2005: Structured Content & XML" badge="Information Architecture">
    <dl class="grid sm:grid-cols-3 gap-3 text-xs sm:text-sm m-0">
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Tooling</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">DocBook, DITA, Oxygen XML Editor, DITA Open Toolkit</dd>
      </div>
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Problem Addressed</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">Large-scale technical documentation consistency, reuse, and single-source publishing</dd>
      </div>
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Lesson Learned</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">Information typing and modularity are essential, but heavy XML pipelines impose severe friction</dd>
      </div>
    </dl>
  </ConceptCard>
</div>

---

## 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.

<div class="my-6">
  <ConceptCard title="Phase 4 · 2010: Static Generators & Docs-as-Code" badge="Predictable Builds">
    <dl class="grid sm:grid-cols-3 gap-3 text-xs sm:text-sm m-0">
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Tooling</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">Python Sphinx, reStructuredText, Subversion, Git, VS Code, Emacs</dd>
      </div>
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Problem Addressed</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">Bridging engineering workflows with documentation; replacing database CMSes with build-time generation</dd>
      </div>
      <div>
        <dt class="font-bold text-gray-900 dark:text-white">Lesson Learned</dt>
        <dd class="text-gray-600 dark:text-slate-300 m-0">Version control provides safer collaboration, granular line-by-line diffs, and reproducible output</dd>
      </div>
    </dl>
  </ConceptCard>
</div>

<blockquote class="border-l-4 border-emerald-500 pl-4 py-2 my-6 bg-emerald-50/50 dark:bg-emerald-950/20 text-emerald-950 dark:text-emerald-200">
**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.
</blockquote>

---

## 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](https://redaction-technique.org/manage-content-in-files-not-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:

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
  <ConceptCard title="Conventional CMS (WordPress / Drupal)" subtitle="Accessible browser editing">
    <ul class="space-y-1 text-sm">
      <li>• <strong>Strengths:</strong> Browser forms, visual media management, zero Git learning curve for non-technical staff</li>
      <li>• <strong>Trade-offs:</strong> Database administration, security patch cycles, plugin debt, content buried in relational tables</li>
      <li>• <strong>Best fit:</strong> Distributed volunteer teams, frequent ad-hoc contributors without developer support</li>
    </ul>
  </ConceptCard>
  <ConceptCard title="Git + Markdown + Astro" subtitle="History, speed, and total control">
    <ul class="space-y-1 text-sm">
      <li>• <strong>Strengths:</strong> Transparent diffs, PR reviews, lightning-fast static builds, zero database vulnerabilities</li>
      <li>• <strong>Trade-offs:</strong> Requires basic Git knowledge or a dedicated form wrapper for non-technical editors</li>
      <li>• <strong>Best fit:</strong> Technical writers, developer docs, content developers, and agile digital publications</li>
    </ul>
  </ConceptCard>
</div>

### Modern docs-as-code architecture

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

<div class="my-6">

</div>

---

## 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:

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
  <ConceptCard title="1. From raw HTML to CMS" badge="Usability">
    Simplifying publishing allowed organizations to democratize web contribution, liberating non-technical teams from manual coding bottlenecks.
  </ConceptCard>
  <ConceptCard title="2. From unstructured to structured content" badge="Scalability">
    Separating content from presentation and adopting modular information types proved indispensable for long-term consistency and reuse.
  </ConceptCard>
  <ConceptCard title="3. From dynamic databases to static sites" badge="Performance">
    Pre-rendering pages at build time eliminates database query overhead, server vulnerabilities, and hosting infrastructure maintenance.
  </ConceptCard>
  <ConceptCard title="4. From CMS dependence to Git workflows" badge="Simplicity">
    Treating documentation as code unlocks powerful peer reviews, reproducible builds, and developer alignment without CMS friction.
  </ConceptCard>
  <ConceptCard title="5. Understanding low-level mechanics matters" badge="Foundations">
    Grasping HTTP requests, HTML structure, and rendering pipelines enables sharper architectural choices—and smarter, more discerning use of AI tools.
  </ConceptCard>
  <ConceptCard title="6. Version control is the critical backbone" badge="Integrity">
    Subversion and Git transformed change management from guessing timestamps to line-by-line traceability and safe concurrent collaboration.
  </ConceptCard>
</div>

---

## 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](https://docs.redaction-technique.org/en/tech-writing-process/version-control-systems/) - the version-control backbone of this workflow.
- [Git: from file to content](https://docs.redaction-technique.org/en/tech-writing-process/git-from-file-to-content/) - moving from files to managed content.
- [Integrating documentation into development](https://docs.redaction-technique.org/en/tech-writing-process/integrating-documentation-into-development/) - docs inside the development workflow.
- [DITA XML to Markdown: lightweight information typing](https://redaction-technique.org/dita-xml-to-markdown-lightweight-information-typing) - how information typing survived the shift from XML to plain text.
- [Manage content in files, not databases](https://redaction-technique.org/manage-content-in-files-not-databases) - the architectural rationale for file-backed publishing.

## External sources

- [The static-site end state](https://en.wikipedia.org/wiki/Static_site_generator)
- [Sphinx/reStructuredText era of the journey](https://www.sphinx-doc.org/)
- [Git as the workflow backbone](https://git-scm.com/)

<small>*Hero image: ["Scribers Lane SINC from Slade Lane back to the stepping stones - River Cole"](https://www.flickr.com/photos/ell-r-brown/49942030998) by [Elliott Brown](https://www.flickr.com/photos/ell-r-brown/), licensed under [CC BY-NC-SA 2.0](https://creativecommons.org/licenses/by-nc-sa/2.0/).*</small>

---

Source: https://redaction-technique.org/web-journey-html-to-git-markdown