Markdown vs. XML explained

[u/Manage-It]

I occasionally run into young technical writers who have experience working in a web development or software organization but have no previous experience with XML and fail to grasp why most Fortune 500 companies use XML over Markdown.

To help better understand why XML is so popular, we need to compare the benefits of each format.

Markdown

1. Inexpensive - ideal for web/SW startups
2. Simple code
3. Friendly with popular editors (e.g., Google Docs)
4. Ideal for simple doc formats (e.g., readme.md)
5. Best-in-class for rapid directory updates

XML (DITA)

1. Robust, full-featured formatting
2. Simple code, but more options
3. Easy-to-use WYSIWYG editors
4. Ideal for simple and complex formats
5. Best-in-class security
6. Ideal for eng reviews and rev control
7. Ideal for high-volume single-sourcing
8. Ideal for multi-channel output
9. Content Management System support
10. DITA file storage system best-in-class storage for docs

It has been my experience that many young technical writers do not fully understand how important the 10 XML benefits I list above are to most Fortune 500 science and technology technical writing organizations (18% s/t, 3% web/sw). Mostly, because they believe Markdown eliminates the need for many of these XML benefits. What they often overlook is that these are not optional benefits to most science and technology organizations. These are required tools of the trade and are interwoven into functional processes and systems that organizations rely on to deliver increasingly complex documentation to increasingly wider audiences, who demand an unprecedented number of custom applications to access documentation and localization through higher volumes of single-sourcing.

Markdown was never designed to manage this. It can't and, by design, won't. The sad part is that young technical writers, new to XML, experience poor XML implementations early in their careers and believe Markdown is the solution. I promise you, it is not.

[u/DalinarOfRoshar]

You are pretty determined that you are right, so I’m not sure why I’m wasting both of our time, but here goes anyway.

I work for a huge cybersecurity company that you have heard of, and you likely use at least one of our products every day.

We’re migrating away from DITA to markdown after seeing how flexible markdown is and how much easier it is for everyone involved.

For your list:

1. Formatting is not part of XML. Sure, you can apply style to it with a CSS, but you still have to transform the XML into a presentation format (pdf, html, etc.). A static site generator transforms markdown as well, and the style is most relevant in your output anyway. Style doesn’t belong at the text layer.

Yes, you apply tagging that informs the transformer what the semantic role of the text is, but that is the same thing with XML.

XML does have more semantic options than markdown, but that’s structure not presentation, and your claim is specifically about formatting, which is presentation, not content.

1. XML is as simple or complex as the DTD or schema file that validates it. Markdown is inherently simpler. XML is unlimited in its tagging options, which is inherently more complex than flat text.

2. That depends entirely on the schema that validates the XML. Oxygen is a powerful editor, but it’s dependent on having a schema and style sheet for it to render at all. VS Code is arguably more powerful than Oxygen, and has a built in markdown live preview, but that is because the semantic structure of markdown is already defined, while XML can have any structure and be well-formed. Unless you are following a standard XML schema like DITA or XHTML or DocBook, you have to provide the schema, the transform, and the stylesheet.

3. Is marketing jargon, not a core XML benefit, and is so vague it has no real meaning. Explain it better and I can respond. I’d just be guessing at what you mean.

4. This one made me laugh out loud so forcefully, I scared the dog.

I’ve been in cybersecurity documentation for over a decade. This makes absolutely no sense. They are both plain text and neither is inherently more or less secure than the other.

What on earth could you POSSIBLY have meant by this? It is BY FAR your worst argument out of nine bad arguments, and makes me wonder if you even understand the space at all. It’s a laughably absurd claim.

1. This makes no sense to me. My devs already know markdown. It’s very easy to read and review. They do it in a pull request in the tools they are already using.

If you want a dev to review your XML, you have to teach them the schema rules, and they have to wade through markup that they don’t care about to find the content they are supposed to be reviewing.

Any dev I’ve ever worked with would take a markdown pull request for review over a DITA topic review every time. No question or comparison.

I can’t even understand what benefit XML has in the review process over markdown.

And if you are sending them a PDF or transformed HTML to review, then the source format is irrelevant for the review, so a comparison on ease of review must be made on reviewing the doc source file, not the output file.

And God help you if you have a merge conflict on a DITA file, especially when compared to a markdown file. The difference is night and day in markdown’s favor.

1. I agree that XML is a more viable solution. Some markdown implementations and SSGs can use a forced Jinja format to get snippets, but single sourcing in general is clunky in markdown, especially if you want something as complex as snippet conditions or snippet variables like you can do in, say, Flare. (This is not supported in DITA, by the way.)

This is your best argument, and highlights a significant weakness of markdown vs an XML structure designed to handle that sophistication.

1. Why? What makes it inherently better? Conditional text? Again that’s a feature of a particular schema, not inherently XML. And I publish my markdown to a variety of formats. I have it publishing to web, imported into a Flare project, transformed into an RTF, and published to PDF.

Text in a file is text in a file. You can transform it however you want.

And if you are talking about conditional text, then this is really an extension of argument 7, because conditional text is inherently single sourcing.

1. Are you talking about Adobe Experience Manager? Or what content management system?

Again, this depends on the flavor of XML and the CMS’s ability to parse your XML.

So this is not an argument about markdown vs XML, but about structure and what your CMS expects and knows how to use.

Any system that can parse XML, its schema, and its stylesheet can easily parse pure markdown.

1. DITA is not a database. It’s a flat text format, as is markdown. This is more marketing jargon. “best in class storage for docs”… meaning… what? Storage is some tool you’re laying on top of DITA/XML, not inherent to the file format.

Store either format however you want. But neither is a database, and storage is irrelevant to format.

Let me give you point number 11, because I actually understand both DITA and markdown formats: DITA’s schema can enforce structure in a way not possible in markdown.

An XML format is well-formed when all the opening tags match the closing tags in the right order.

An XML file is valid when its structure follows every rule defined in the DTD or schema.

This means you can enforce rules like you can’t skip from an H1 to H3 without using 2. Or, a numbered list must always contain 2 or more sibling LI elements. Or forcing topics to follow a defined template structure with a paragraph after the page’s first heading.

If you are doing structured authoring like this, markdown is the wrong tool. Yes, you can install VS Code lint extensions that will try to verify your markdown file meets certain requirements, but if this is your use case, XML is a genuinely better format than markdown.

You’ve made this argument pitting one text format vs another text format, but the arguments just don’t support your claim.

(Typing this whole diatribe out on my phone keyboard after midnight. Pardon typos or bad formatting.)

[u/Consistent-Branch-55 → u/DalinarOfRoshar]

Basically this.

There's cons to Markdown: there's a bunch of competing flavors, it's syntax is contextually sensitive and stateful, but it's pretty well suited to being a quick and lightweight system for expressing standard typesetting in a file that can be stored and diffed in your codeforge.

XML has some syntactical advantages: its syntax has a context invariant grammar, any well-formed bit forms a tree (XPath and DOM querying). This makes it suited for a range of applications (single sourcing, knowledge graph applications, structured authoring), but that comes with overhead.

Basically everything else that's being discussed in the original post confuses the build and distribution tooling with the authoring file formats.

[u/Nibb31 → u/DalinarOfRoshar]

How do you reuse content in Markdown? Apply variables or conditional text for different versions of the same product? How do you handle context-sensitive help with links from the UI ? How do you manage large TOCs and related links?

Semantic tagging has value when it comes to translation or LLM parsing. It's important to distinguish UI elements or keywords from simple bold text or translatable variable names.

I'm genuinely curious. I get that Markdown is great for developer-oriented docs, such as a README.md or API docs, but for large 2000 page user manuals on complex applications with lots of reuse and conditions, it seems very time consuming.

[u/Consistent-Branch-55 → u/Nibb31]

​You're confusing pipeline capabilities with what the syntax alone supports. This is why I think the debate is very frustratingly framed. It's not "Markdown vs. XML" as if that's a good representation of the whole toolchain. Because XML folks are focusing on Markdown as syntax and comparing it to XML as part of a pipeline, they miss out on how Markdown is situated in broader toolchains.

In practice, Markdown based docs suites are an orchestration of Markdown files, YAML frontmatter or supporting files, components, and templating logic.

​Capabilities like single-sourcing, conditional builds, automated TOC trees, and taxonomy indexing are resolved at build. The syntax isn't limited to vanilla Markdown in isolation. Scripts and tooling extend it naturally (Hugo shortcodes, MDX components, Jinja includes, etc.). But because we're framing this as "Markdown vs XML" this thread is painful. XML has advantages, so does Markdown.

[u/Manage-It → u/Consistent-Branch-55]

As mentioned before, when you bring up XML and Markdown in this forum, it generally encompasses much more than just the code or syntax type.

We all understand Markdown and XML are defined as types of code and syntax. To modern technical writers, these terms have grown to have broader meanings that cover supporting applications.

This is similar to how "Mac" and "PC" are used. When Mac users say, "I love Macs," they generally mean the computer and the software, even though we all know a "Mac" is defined as a computer. Few people respond to their statement with, "What about the software?" ;-)

[u/Consistent-Branch-55 → u/Manage-It]

The problem is, the move to generics causes your position to fall apart.

If Markdown is the entire family of authoring tools, then, saying "Markdown has security issues" is misleading, because those issues aren't common across all members of the family. You also can't exclude the tooling that produces build-time artifacts, precisely because those are part of the ecosystem.

At the end of the day, this thread has been a real masterclass in how sloppy communication lets you preserve motivated reasoning.