Let’s walk through exactly what you need to do to get that first paragraph recognized as <shortdesc> and output properly in your HTML5:

1. Structure your MDITA file as a LwDITA-compatible Topic #

First, your markdown file needs to follow LwDITA’s MDITA topic rules (not just regular markdown). The correct structure looks like this:

# Your Topic Title
This is the shortdesc paragraph — it’ll be mapped to <shortdesc> in the DITA output.

This is the first paragraph of your topic body.
Any subsequent content here becomes part of the main topic content.

Key detail: The first paragraph right after the topic title (even with a blank line in between) is automatically treated as the shortdesc.

2. Update your ditamap to recognize MDITA content #

In your sequence.ditamap, explicitly mark your MDITA topic references with format="mdita" so DITA OT knows to process them as LwDITA content, not regular markdown. Here’s an example snippet:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Your Sequence Map</title>
  <!-- Reference MDITA files with format="mdita" -->
  <topicref href="your-topic-file.md" format="mdita"/>
</map>

3. Confirm the LwDITA plugin is installed #

DITA OT 3.0.3 should include the org.lwdita plugin by default, but if you’ve customized your installation, check if it exists in the plugins folder of your DITA OT directory. If missing, install it with this command:

dita install org.lwdita

4. Use the optimized conversion command #

Instead of the generic html5 format, use the dedicated lwdita-html5 format to ensure proper handling of LwDITA-specific elements like shortdesc:

dita --input=sequence.ditamap --format lwdita-html5

The standard html5 format will also work if your MDITA files are correctly referenced, but lwdita-html5 is tailored for LwDITA content.

5. (Optional) Define shortdesc explicitly for more control #

If you need to override the automatic first-paragraph rule (e.g., your shortdesc isn’t the opening paragraph), use a YAML front matter block to set it explicitly:

---
shortdesc: "This is my explicit shortdesc, regardless of the first paragraph."
---
# Your Topic Title
This paragraph will now be part of the main body content.

DITA OT 3.0.3 supports parsing YAML front matter for MDITA topics, so this will take precedence over the default behavior.

After following these steps, your shortdesc should appear in the HTML5 output — usually as a distinct section (often with a shortdesc class that you can style with CSS if needed).

内容的提问来源于stack exchange，提问作者tkhm