AEM Guides (AEMaaCS): DITAMap: Site creates pages but Markdown content not injected (SAXException) | Community
Skip to main content
akshayrathnavas
akshayrathnavas
Level 1
January 21, 2026
Question

AEM Guides (AEMaaCS): DITAMap: Site creates pages but Markdown content not injected (SAXException)

  • January 21, 2026
  • 2 replies
  • 18 views

I’m facing an issue with AEM Guides on AEM as a Cloud Service while generating Sites output from a DITAMap that references Markdown topics using this documentation: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/authoring/webeditor/markdown-in-dita-and-aem-guides

What I’m seeing:

  • The DITAMap → Site generation runs

  • Site pages do get created

  • Page properties (sourcePath, UUIDs, map references, etc.) are all set correctly along with the hierarchy of nodes.

  • However, the content is missing - the “injected-container” on the page is empty

  • This preset works for normal dita topics.

Error in logs:

Markdown resource cannot be read as an XML Document org.xml.sax.SAXException

This happens during the NodeJS-based publishing workflow, specifically while Guides is extracting dependencies / DTD rules. From the stack trace, it looks like the Markdown file is being attempted to be read as an XML document.

Pages are created but the Markdown content never gets injected into the page

Environment details:

  • Adobe Experience Manager 2026.1.23963.20260108T001551Z-251200

  • AEM Guides 2025.11.0.301

  • Source content: Markdown (.md) referenced directly from the DITAMap

At this point, I’m trying to understand:

  • Is Markdown-based DITAMap → Sites generation fully supported on AEMaaCS?

  • Or is this a known limitation/bug with the NodeJS publishing pipeline for Markdown topics or should I make any custom preset with plugins to make it work? 

If anyone has successfully used Markdown topics for Sites output on AEMaaCS, or has run into this error before, I’d really appreciate any guidance or confirmation.

2 replies

kautuk_sahni
Community Manager
kautuk_sahniCommunity Manager
Community Manager
February 2, 2026

​@Anudeep_Garnepudi ​@DivrajSingh ​@lsteinbacher Tagging you to see if you might want to share any best practices or insights on this topic. Your expertise would be greatly appreciated, thank you!

Kautuk Sahni
AmitVishwakarma
Community Advisor
AmitVishwakarmaCommunity Advisor
Community Advisor
February 2, 2026

Hi ​@akshayrathnavas ,

Yes, Markdown topics in a DITAMap => AEM Site output are supported on AEMaaCS, but only if they are used in the “Markdown in DITA” way that Guides expects.
Your symptoms (pages created, injected-container empty, SAXException “Markdown resource cannot be read as an XML Document”) mean Guides is trying to treat the .md as XML, i.e. it’s not recognizing it as Markdown.

In practice this almost always comes down to missing or wrong format on the topicref.

What you should do / check: Use the pattern from Use Markdown in AEM Guides.https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/authoring/webeditor/markdown-in-dita-and-aem-guides

1. DITAMap must flag Markdown topics with format="markdown" or format="mdita"
Example:

<map>
  <topicref href="topics/intro.md"
            format="markdown"
            navtitle="Intro (MD)"/>
</map>

or:

<topicref href="topics/intro.md"
          format="mdita"
          navtitle="Intro (MD)"/>

Without this, the NodeJS/XML pipeline tries to load the .md as XML and you get the SAXException you’re seeing.

2. No extra DTD/DTD‑style processing on the .md

  • Make sure the .md is stored as a binary/plain DAM asset under /content/dam, not as a DITA topic with a DTD.
  • The DITAMap is what gets parsed as XML, the .md is fed to the Markdown backend.

3. Use an AEM Site preset (Native AEM Site route)

  • Use the standard AEM Sites preset based on the Native AEM Site route (the NodeJS‑based publisher described in the architecture doc).
  • The fact that pure DITA topics work in the same preset confirms your preset and microservice config are basically fine.

4. Supported scenario / limitations

Per the Markdown KB article:https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/authoring/webeditor/markdown-in-dita-and-aem-guides

  • Option 1 (what you’re doing): Use Markdown directly in a DITAMap with format="markdown" / format="mdita" > Works for web (HTML5 / AEM Site) and PDF via publishing microservices, but:
    • More limited around full DITA features (advanced reuse, conditions, etc.).
    • Option 2: Convert .md => DITA first, then publish as normal DITA.

So your use case (DITAMap referencing .md topics to AEM Site) is supported as long as the DITAMap is annotated correctly.

    Terms & ConditionsAccessibility statement

    Loading footer...