Why Your Archives Deserve Better Than Markdown

If you've ever tried to open a document from 15 years ago, you know the anxiety. Will the app still exist? Will the formatting survive? Will a future developer even understand what flavor of syntax was used?

Markdown has become the default for developer documentation — and for good reason. It's lightweight, readable, and widely supported. But "widely supported" is doing a lot of heavy lifting in that sentence. Because the uncomfortable truth is: Markdown has a fragmentation problem, and that makes it a poor choice for anything you want to last.

The Markdown Flavor Problem

Ask ten developers what valid Markdown looks like and you'll get ten slightly different answers. There's:

• CommonMark


• GitHub Flavored Markdown (GFM)


• MultiMarkdown


• Pandoc Markdown


• Reddit Markdown


• ...and many more

Each flavor handles edge cases differently — tables, footnotes, nested lists, inline HTML. A document written in GFM today might render incorrectly in a CommonMark parser a decade from now. And critically, there's nothing in the file itself to tell a future reader which flavor was used.

Open a .md file in the year 2045 and good luck knowing what spec it was written against.

Enter Celes

Celes is a tag-based markup language that takes a different approach. Here's what a Celes document looks like:

<!Celes-0.1>

<header -size=1>{Why Archives Matter}

<line>{This is a <bold>{bold} word in a paragraph.}

<list -bullet=circle>{First item}

<list -bullet=circle>{Second item}

<blockquote>{Preserve knowledge for the future.}

It maps cleanly from Markdown concepts but with one critical difference: the version is baked right into the file.

That <!Celes-0.1> declaration at the top tells any future parser, human or machine, exactly what spec was used to write this document. No ambiguity. No guessing.

What Makes Celes Good for Long-Term Archival

1. Explicit versioning

Every Celes file declares its spec version on line one. Future tools can branch their parsing logic by version. Future humans know exactly what they're reading.

2. Unambiguous tag-based syntax

Where Markdown relies on whitespace, indentation, and subtle punctuation rules that vary by flavor, Celes uses a consistent <tag>{content} structure with named attributes like -size=1 or -bullet=circle. There's far less room for parser ambiguity.

3. Plain text at heart

Like Markdown, Celes is plain text. It will open in any text editor in any decade. No proprietary format, no binary encoding, no dependency on a specific application.

4. Convertible

Celes ships with built-in converters to and from Markdown and HTML:

import celes



# Convert Markdown to Celes for archival

celes_output = celes.convert_md_to_celes(my_markdown)



# Convert back to Markdown or render to HTML anytime

html_output = celes.parse_celes(celes_output)

You don't have to abandon your existing Markdown workflow. Convert on the way into the archive.

A Real-World Example

We recently converted the Godot Engine's documentation files — README, AUTHORS, CONTRIBUTING, DONORS — from Markdown to Celes. The conversion was clean, lossless, and the resulting files are self-describing in a way the originals weren't.

A developer in 2045 picking up README.celes will see <!Celes-0.1> and immediately know the rules of the road. The same developer picking up README.md would be left guessing.

Who Should Care About This

• 
  Open source projects that want their documentation to outlive any particular platform or toolchain


• 
  Libraries and institutions digitizing historical records


• 
  Personal knowledge bases and journals you want to read in retirement


• 
  Legal and compliance teams storing long-lived documents


• Anyone building a time capsule of knowledge

Getting Started

pip install celes

import celes



# Parse Celes to HTML

html = celes.parse_celes(source)



# Convert from Markdown

celes_doc = celes.convert_md_to_celes(markdown_source)



# Convert back to Markdown

md_doc = celes.convert_celes_to_md(celes_source)

The Bottom Line

Markdown is great for today. Celes is designed for decades from now.

If you're building something meant to last — documentation, archives, knowledge bases — the explicit versioning and unambiguous syntax of Celes makes it a more honest choice than hoping the right Markdown flavor is still around when someone needs your files.

The best archive format is one that tells the future exactly how to read it. Celes does that from line one.

Have you thought about the long-term survival of your documentation? Drop your thoughts in the comments.