Markdown is one of those tools we see so often that we stop noticing it. We open a README on GitHub - Markdown. We write a note in Obsidian - Markdown. We prepare project documentation, a pull request checklist, an issue comment, a task description, a work plan for an AI agent - very often, Markdown again. Even when an application shows us a nice editor, underneath it there is often plain text with a few characters that give it structure.

At first glance, it is only a more convenient way to write headings, lists, and links. HTML for people who do not feel like writing HTML. But the longer I work with documentation, code, and tools based on large language models, the stronger my impression becomes that the matter is more complex and more interesting.

Markdown is no longer just a text format. More and more often, it is a language for communicating intent. A language in which a human describes a goal, context, constraints, and quality criteria, while a machine tries to turn that into action.

Does this mean Markdown has become a programming language? Not in the classic sense. But perhaps it is starting to occupy a place even higher: above high-level programming languages, as a layer for describing work for systems that can generate code, run tools, and make decisions within the scope of a task.

Where Did Markdown Come From?

Markdown was published in 2004 by John Gruber. Aaron Swartz helped with the syntax design. The idea was simple: create a format in which we can write text that remains readable to humans and can later be converted into valid HTML.

That matters, because at the time the Internet was already full of content, but writing that content in HTML was not very convenient. A short paragraph with a link looked more or less like this:

<p>
  Read the documentation on the
  <a href="https://example.com">project website</a>.
</p>

Of course, this works. The problem is that in plain text, markup starts competing with the content. A person wanted to write a sentence, but had to think about tags, attributes, brackets, and closing elements. And, on top of that, nesting them correctly.

In Markdown, the same example is closer to natural language:

Read the documentation on the [project website](https://example.com).

The difference is not only about the number of characters. The point is that the text still looks like text. Even without rendering, we know what is a link, what is a heading, what is a list, and what is a code fragment.

Gruber wrote that the main goal of Markdown's syntax was readability. A document was supposed to be publishable as plain text, without giving the impression that someone had scattered technical markup across it. That assumption turned out to be more important than it might have seemed in 2004.

A Format That Does Not Try to Be Too Smart

Markdown won in many places precisely because it does not try to do everything. It has no elaborate styling system. It does not try to replace a word processor. It does not force one working environment. It does not require a special program just to be readable. In the worst case, we open a .md file in a regular editor and still understand most of the content.

This is a boring feature, but in practice it is very valuable. A Word file without Word can be a problem. A document locked inside a closed tool depends on that tool. Markdown is plain text. We can keep it in Git, compare it in a diff, search it, generate it, parse it, copy it between systems, and archive it for years.

In a programmer's work, details like this matter. Documentation does not live in an ideal world. It is read in the browser, in the terminal, in the code editor, in a pull request, in a wiki system, and sometimes in a raw file. Markdown handles these "moves" well.

In short: Markdown is structured enough for machines and natural enough for humans.

Markdown as a Language of Everyday Programming Work

If we look at a modern software project, Markdown appears almost everywhere.

In README.md, we describe what the project is, how to run it, and what it requires. In CHANGELOG.md, we record changes between versions. In architecture documentation, we explain decisions that are not directly visible in the code. In issues and pull requests, we describe context, acceptance criteria, risks, and things to check.

Take a simple task description:

## Goal

Add e-mail address validation to the signup form.

## Acceptance Criteria

- The user sees an error message after entering an invalid address.
- The form does not submit data if the address is invalid.
- The test covers both a valid and an invalid address.

This is not code. And yet such a description really does steer the work of a team. It defines the scope, the order of thinking, and the definition of success. What is more, it is easy for tools to process. A system can find the "Acceptance Criteria" section, an agent can turn it into a checklist, and a human can quickly assess whether the task is well described.

Markdown has therefore started to perform a function that cannot be reduced to formatting. It has become a simple way to write down the structure of thinking.

From Text to Intent

Let us pay attention to one more thing. Markdown does not only say: "this text should be larger", "this fragment should be bold", "this is a list". Very often, it says:

• this is the goal,
• this is the context,
• these are the constraints,
• these are the steps,
• this is an example,
• this is code,
• this is the result we expect.

Of course, Markdown itself does not understand these concepts. A parser sees headings, lists, and code blocks. But for a human, a team, and increasingly for a language model, this simple structure is enough to reconstruct the meaning of a document.

That is why Markdown has fit so well into work with AI agents. An agent needs context, instructions, examples, constraints, and quality criteria. Markdown lets us write all of that without designing a separate data format.

We can write:

## Task

Move form validation into a separate function.

## Constraints

- Do not change the component's public API.
- Do not touch the styles.
- Add a test for an empty field.

## Definition of Done

- Form tests pass.
- The code is more readable than before.

For a classic compiler, this is plain text. For an agent, it is already a fairly precise work instruction. It has a goal, boundaries, scope, and verification criteria. We are not describing loops, conditions, or data structures. We are describing intent.

Is Markdown a Programming Language?

Here it is worth being careful, because it is easy to drift into a claim that is too strong. Markdown is not a programming language in the traditional sense. It does not execute anything by itself. It has no types, functions, exceptions, control flow, or standard library. By itself, it will not calculate tax, fetch data from an API, or write a record to a database.

But the question that interests me is different: in work with AI systems, is Markdown starting to play a role similar to a control language?

In classic programming, high-level languages describe a procedure. We can write in Python, JavaScript, PHP, Ruby, or Go, but we are still telling the computer how to move from input data to a result. The abstraction is higher than in assembler, but the execution logic still sits on our side.

Programmers defending the superiority of working with code often forget that they also do not directly control how their instructions will be translated into machine language.

In work with an agent, we increasingly do something else. We do not describe exactly how to solve the problem. We describe what we want to achieve, in what context, with what constraints, and how we will know that the result is good.

This is a level of abstraction above a typical high-level programming language. Not because Markdown is "better" than programming languages. That would make no sense. Markdown will not replace the language in which we build an application. But it can become the language in which we describe work that will later be performed by a system capable of using those languages.

In other words: a high-level language tells a machine how to execute a program. Markdown, in agent-based work, increasingly tells a machine what program or change it should prepare in the first place.

Why Markdown?

One might ask: why not JSON, YAML, or XML? After all, all these formats are suitable for passing structured data.

The answer is simple: because Markdown is friendlier to humans. JSON works very well as a data format. YAML is often convenient for configuration. XML still has its place in integrations and documents. But when we want to combine description, context, examples, code, and project decisions, Markdown feels more natural.

Let us compare two ways of writing the same intent.

{
  "task": "Add tests for the form",
  "constraints": [
    "Do not change the public API",
    "Do not touch the styles"
  ],
  "done": [
    "The test covers valid data",
    "The test covers an invalid e-mail address"
  ]
}

This is precise, but not very convenient as a note for a human. Now Markdown:

## Task

Add tests for the form.

## Constraints

- Do not change the public API.
- Do not touch the styles.

## Done When

- The test covers valid data.
- The test covers an invalid e-mail address.

The second version is less formal, and at the same time easier for the "protein interface" to digest. We can add an explanatory paragraph, paste a code fragment, add a link to a pull request, quote a decision from a conversation, and still not destroy the readability of the document.

This is exactly the kind of flexibility we need when working with people and agents. A format that is too rigid requires tools. Text that is too loose loses structure. Markdown sits in the middle.

Extensions, or the Price of Popularity

Of course, Markdown's story is not perfect. Simplicity had its price.

The original Markdown was described more as a practical syntax and tool than as a very formal specification. When the format started being used in many places, differences between implementations appeared. One version supported tables, another footnotes, another task lists with checkboxes. Sometimes the same document rendered differently in two tools.

That is where CommonMark comes in: an attempt to tighten the syntax and prepare a test suite. There is also GitHub Flavored Markdown, which extended Markdown with things needed in everyday GitHub work, such as tables, strikethrough, and task lists.

Then more worlds appeared:

• MDX lets us combine Markdown with JSX components,
• Pandoc can convert documents between many formats,
• Marp uses Markdown to create presentations,
• Mermaid lets us write diagrams as text,
• many tools add math, footnotes, metadata, and their own extensions.

Is it still the same Markdown? In most cases, yes, but we need to remember the context. Markdown on GitHub, Markdown in Obsidian, Markdown in a static site generator, and Markdown in a documentation system may differ in details.

In practice, it is worth asking one question: which rendering engine are we writing for? If the text is meant only for humans, the differences are less painful. If it is supposed to feed a publishing pipeline, product documentation, or an agent workflow, syntax details start to matter.

What Can Go Wrong?

Markdown is simple, but it is not magic. The first problem is a false sense of standardization. A .md file looks innocent, so we assume it will work the same everywhere. Then it turns out that tables render differently, HTML is sanitized, checkboxes do not work, and code blocks require a different language marker.

The second problem is mixing a document with an application. MDX and similar tools are very convenient, but when a lot of components, imports, and logic start appearing in the text, we lose part of Markdown's original advantage. The raw file stops being easy to read.

The third problem concerns work with AI. Markdown is great for describing tasks, but it does not guarantee execution. An agent may misunderstand a section, skip a constraint, or treat an example as a rule. Structure helps, but it does not replace validation, tests, and review.

So it is worth not confusing a readable description with a formal specification. Markdown can be a very good interface, but we still need mechanisms that check whether the result is correct.

When Does Markdown Make the Most Sense?

Markdown works best where content has to be readable, versionable, and possible to process with tools at the same time.

If we write documentation for programmers, it is hard to find a more natural choice. We can keep code examples next to explanations. We can review documentation in pull requests. We can generate a website, a PDF, or content fragments used in an application, such as tooltips, error messages, or changelog elements.

If we work with AI agents, Markdown is a good format for describing tasks, plans, decisions, and reports. Headings organize context, lists simplify requirements, code blocks separate instructions from examples, and quotes help preserve a source fragment from a conversation or document.

However, if we need a hard contract between systems, Markdown may be too soft. An API is better described with a schema. Data is better sent as JSON. Complex configuration is better kept in a format that can be validated. Markdown is great as a communication layer, but not always as a data source for a system.

Summary

Markdown survived because it is modest. It does not require a large investment from us, it does not lock us into one tool, and it does not pretend to be a complete working environment. It is plain text that can carry a surprising amount of meaning.

It started as a more convenient way to write content for the Internet. Then it became the default format for technical documentation. Today, it is increasingly also a format for talking to machines: in prompts, instructions, work plans, reports, and definitions of done.

I would not say that Markdown replaces programming languages. That would be a bad thesis. I would rather say that it has appeared above them as a simple language of intent. A human describes in it what should happen. An agent, a tool, or a team tries to turn that description into a concrete change.

And perhaps that is exactly why Markdown is so interesting. It did not win because it was the most formal. It won because it was formal enough to help machines and natural enough for us to still want to write in it.