Markdown Syntax Visualization

Most documentation dies in a silo. Whether it’s locked in a proprietary Notion database or buried in a Google Doc that requires three rounds of SSO just to view a table, we’ve allowed our technical knowledge to become ephemeral. This is a systemic failure of engineering discipline.

If your documentation isn’t in plain text, you don’t own it.

I use Markdown because it is the only format that respects the long-term memory of a system. It is human-readable, it is LLM-optimized, and it doesn’t expire when a startup goes out of business.

The Standard: Goldmark and CommonMark

Hugo uses Goldmark. It’s a high-performance parser written in Go that adheres to the CommonMark standard. This is critical. In my experience, “extended” Markdown flavors that introduce non-standard syntax are just another form of vendor lock-in.

Stick to the primitives. They are the only things that will be readable in twenty years.

Primitives of High-Signal Writing

Effective documentation requires semantic precision.

  • Headings (#): Use them to define a clear hierarchy. Don’t skip levels. A document without a logical structure is just a stream of consciousness, which is useless for an AI agent trying to help you debug a dangling object in production.
  • Fenced Code Blocks: These are the lifeblood of technical writing. Goldmark handles syntax highlighting without requiring a bloated JavaScript runtime on the client side.
// Code as a first-class citizen
func main() {
    log.Println("Building for the long-term")
}

Writing for the Machine

We no longer write exclusively for humans. We write for AI agents that need to parse our intent in milliseconds.

  1. Tables: Use them for structured comparisons. They provide high-density information that is easy to ingest.
  2. Task Lists: Use - [ ] and - [x]. They are the simplest semantic markers of progress.
  3. No Magic: Avoid shortcodes where a standard Markdown pattern exists. Magic is a vulnerability.

The Bottom Line

A README in a git repo is worth more than a thousand pages in a “knowledge management” platform. By keeping our content in Markdown, we ensure it remains a place for serious work—free from the bloat of modern SaaS and ready for the future of automated engineering.

Further Reading

Conclusion

Documentation is an engineering artifact. Treat it like one. Use plain text, pin your standards, and stop trusting your knowledge to platforms that won’t exist in a decade.