jelovirt / org.lwdita

LwDITA parser for DITA-OT

Lightweight DITA for DITA-OT

The DITA-OT LwDITA plug-in supersedes the previously released Markdown plug-in for DITA-OT and adds additional features to support Lightweight DITA.

Note The LwDITA plug-in is included in DITA Open Toolkit 3.0 and newer.

It contains:

• a custom parser for Markdown and HTML to allow using MDITA and HDITA as a source document format,
• and a transtype to generate Markdown from DITA source.

The Markdown DITA files need to use a subset of Markdown constructs for compatibility with DITA content models.

Usage

Using LwDITA files as input

Markdown DITA or HTML DITA topics can only be used by linking to them in map files.

<map>
  <topicref href="test.md" format="mdita"/>
  <topicref href="test.html" format="hdita"/>
</map>

The format attribute value must be set to mdita or hdita in order to recognize files as Markdown DITA or HTML DITA, respectively; the file extension is not used to recognize format.

See the syntax reference for XML and Markdown DITA correspondence.

Generating Markdown output

The DITA-OT LwDITA plug-in extends the DITA Open Toolkit with additional output formats (transformation types) that can be used to publish DITA content as Markdown.

• To publish Markdown DITA files, use the markdown transtype.

• To generate GitHub Flavored Markdown files, use the markdown_github transtype.

• To publish GitHub Flavored Markdown and generate a SUMMARY.md table of contents file for publication via GitBook, use the markdown_gitbook transtype.

Requirements

LwDITA plug-in	DITA-OT	Java
≤ 2.5	2.4	1.8
≥ 3.0	3.4	1.8
≥ 4.0	3.4	11
≥ 5.2	3.4 1	11

Install

1. Run the plug-in installation command:

   On DITA-OT version 3.5 and newer:

   $ dita install org.lwdita

   On DITA-OT version 3.2–3.4:

   $ dita --install org.lwdita

   On DITA-OT version 3.1 and older:

   $ dita --install https://github.com/jelovirt/org.lwdita/releases/download/2.3.2/org.lwdita-2.3.2.zip

The dita command line tool requires no additional configuration; running DITA-OT using Ant requires adding plug-in contributed JAR files to the CLASSPATH with e.g. -lib plugins/org.lwdita.

Build

To build the DITA-OT Markdown plug-in from source:

1. Run the Gradle distribution task to generate the plug-in distribution package:

   ./gradlew dist

   The distribution ZIP file is generated under build/distributions.

Release

To release and build distribution:

1. Tag release in master branch using semantic version as tag name, e.g. 1.2.3.

   GitHub Actions will create

   • a distribution ZIP and upload it to GitHub Release for the tag,
   • a JAR release that is published to github.com/jelovirt/org.lwdita/packages,
   • a pull request to github.com/dita-ot/registry to update the release to DITA-OT plug-in registry.

Donating

Support this project and others by @jelovirt via GitHub Sponsors.

License

DITA-OT LwDITA is licensed for use under the Apache License 2.0.

Footnotes

1. Support MDITA map requires DITA-OT version 4.1. ↩

org.lwdita's Issues

Render in published output strikethrough content

A strikethrough in the Markdown content:

      ~~abc~~

is converted in the DITA content to a "ph" with status "deleted".
How about if the plugin could also contribute plugin extensions for HTML and PDF based outputs to convert ph with status="deleted" to content which actually appears strike-through in the published output?

Release has com.elovirta.dita.markdown dependencies

The release package contains dependencies to the original plugin directory ${dita.plugin.com.elovirta.dita.markdown.dir}.

Links not properly generated in output Markdown content when chunking

I try to produce a single Markdown file from all the DITA topics in a DITA Map so I set chunk="to-content" on the map root element. Unfortunately links from one topic to another are not properly computed.
Attaching sample project:

chunk-md.zip

Treat autolinks as external cross references

After the changes in af91422 for #8 (released with org.lwdita 2.0.3 and bundled in DITA-OT 3.0.4), Markdown links wrapped in angle brackets (or “autolinks”) are missing from the output.

The linked URL should be included in the output and treated as a cross reference with the @scope attribute set to external.

DITA publishing to markdown format results in destroyed table layout when <p> is used in table

Dita input file with table that contains <p> in table entry:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd"[]>
<dita>
<topic id="topic_nlw_4hw_mcb">
  <title>Test</title>
  <body>
    <table frame="all" rowsep="1" colsep="1" id="table_wnw_g3w_mcb">
      <title/>
      <tgroup cols="2">
        <colspec colname="c1" colnum="1" colwidth="1*"/>
        <colspec colname="c2" colnum="2" colwidth="1*"/>
        <thead>
          <row>
            <entry>Key</entry>
            <entry>Value</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>Key1</entry>
            <entry>Value1</entry>
          </row>
          <row>
            <entry>Key2</entry>
            <entry><p>Value2</p><p>new paragraph</p></entry>
          </row>
          <row>
            <entry>Key3</entry>
            <entry>Value3</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </body>
</topic>
</dita>

Result of created markdown file after Transformation (source code):

# Test {#topic_nlw_4hw_mcb}

|Key|Value|
|---|-----|
|Key1|Value1|
|Key2|Value2

new paragraph

|
|Key3|Value3|

Result (preview)

Test {#topic_nlw_4hw_mcb}

Key	Value
Key1	Value1
Key2	Value2

new paragraph

|
|Key3|Value3|

MDITA fails on footnotes

While testing the XDITA plug-in per dita-ot/dita-ot#3108 (comment), building output from org.oasis-open.xdita/samples/remotelighting.ditamap failed with an error related to the use of footnotes on Line22 of remote-components.md:

Error: Failed to run pipeline: No renderer configured for com.vladsch.flexmark.ext.footnotes.Footnote

Definition List in HDITA format not supported in MDITA

The specification says in table 7.1 DITA 1.3 element types in LwDITA that definition lists are supported in MDITA by using the HDITA syntax. The definition list in markdown syntax is rendered, the HDITA syntax is not processed. Nothing appears in the PDF output. I'd like to use the HDITA syntax to filter <dlentry> elements.

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="urn:oasis:names:tc:dita:rng:map.rng"
    schematypens="http://relaxng.org/ns/structure/1.0"?>
<map>
    <title>Test</title>
    <topicref href="test.md" format="mdita"/>
</map>

# Test

Shortdesc

Term
:   Definition.

<dl>
    <dlentry>
        <dt>Term</dt>
        <dd>Definition</dd>
    </dlentry>
</dl>

DITA publishing to markdown format does not escape the pipe character within tables that ends in missing table content

I have a dita file that contains the pipe character in a table.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<dita>
  <topic id="id_40a72787efc94c2a8bb6e60f8cac2b2c">
    <title>Test</title>
    <shortdesc>This is a table that contains a pipe character</shortdesc>
    <body>
      <table>
        <tgroup cols="2">
          <colspec colname="col1"/>
          <colspec colname="col2"/>
          <thead>
            <row>
              <entry>First Header </entry>
              <entry>Second Header </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>Cell col1 row1</entry>
              <entry>Cell col2 row1</entry>
            </row>
            <row>
              <entry>Cell col1 row2 | that contains a pipe character after the word row2.</entry>
              <entry>Cell col2 row2</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </body>
  </topic>
</dita>

When I transform with DITA-OT 3.1 the dita file with Option --format=markdown or --format=markdown_github
in the resulting markdown file content of the table is missing!

Result looks like:

Result begin:

Test

This is a table that contains a pipe character

First Header	Second Header
Cell col1 row1	Cell col2 row1
Cell col1 row2	that contains a pipe character after the word row2.

Result end

Expected output should look like:

Expected begin:

Test

This is a table that contains a pipe character

First Header	Second Header
Cell col1 row1	Cell col2 row1
Cell col1 row2 | that contains a pipe character after the word row2.	Cell col2 row2

Expected end

In my opinion a pipe character within tables should be escaped (with | ).

Backslash Escapes not working in Markdown input

dita-ot/dita-ot#3267 (comment)

No renderer configured for com.vladsch.flexmark.ext.aside.AsideBlock

Tested with DITA OT 3.2.1
If I have an invalid Markdown table (the last line of the table does not end in pipe):

    # Title
    
    abc
    
    | P1 | P1 | P3 | P4 |
    | --- | --- | --- | --- |
    |  | R1 | R2

the Markdown to DITA plugin breaks the DITA to HTML output with:

       DITA-OT3.x\plugins\org.dita.base\build_preprocess.xml:62: Failed to run pipeline: No renderer configured for com.vladsch.flexmark.ext.aside.AsideBlock

Ideally either the errors would not be that criptic or there would be some better fallbacks or maybe even some line numbering information would be displayed in the error to instruct the end user as to where the problem is because the Markdown file could be quite large.

XSLT included/imported multiple times warning in "dita.out.map.markdown.toc"

I get lots of warnings like this when using the DITA OT 3.2.1 to generate Markdown from DITA:

 [xslt] Transforming into D:\projects\eXml\samples\dita\flowers\out\markdown
 [xslt] Processing D:\projects\eXml\samples\dita\flowers\temp\markdown\flowers.ditamap to D:\projects\eXml\samples\dita\flowers\out\markdown\index.html
 [xslt] Loading stylesheet D:\projects\eXml\frameworks\dita\DITA-OT3.x\plugins\org.lwdita\xsl\map2markdown-cover.xsl
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\output-message.xsl:30:46: Warning! Stylesheet module plugin:org.dita.base:xsl/common/output-message.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\dita-utilities.xsl:15:54: Warning! Stylesheet module plugin:org.dita.base:xsl/common/dita-utilities.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\functions.xsl:15:40: Warning! Stylesheet module file:/D:/projects/eXml/frameworks/dita/DITA-OT3.x/xsl/common/functions.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\uri-utils.xsl:13:54: Warning! Stylesheet module file:/D:/projects/eXml/frameworks/dita/DITA-OT3.x/xsl/common/uri-utils.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\dita-textonly.xsl:20:4: Warning! Stylesheet module plugin:org.dita.base:xsl/common/dita-textonly.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\topic2textonly.xsl:13:4: Warning! Stylesheet module file:/D:/projects/eXml/frameworks/dita/DITA-OT3.x/xsl/common/topic2textonly.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\map2textonly.xsl:13:4: Warning! Stylesheet module file:/D:/projects/eXml/frameworks/dita/DITA-OT3.x/xsl/common/map2textonly.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
 [xslt] D:\projects\eXml\frameworks\dita\DITA-OT3.x\xsl\common\ui-d2textonly.xsl:13:4: Warning! Stylesheet module file:/D:/projects/eXml/frameworks/dita/DITA-OT3.x/xsl/common/ui-d2textonly.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior

Nested Lists not properly generated in output Markdown content when list Item starts with bold, italics, codeph...

In DITA-OT 3.3 list items that start with bold, italics, codeph tag are intended with 4 spaces instead of 3 while transformed to markdown.
Consequently nested lists appear on the same level as the parent list item. Also in sóme cases following content is interpreted as code block.
DITA xml source:

<ul>				
  <li>
    <b>Item 1 Level 1</b>
    <ul>
      <li>Item 1 Level 2</li>
      <li>Item 2 Level 2</li>
    </ul>
  </li>
  <li>Item 2 Level 1</li>
</ul>

Markdown result when transformed with markdown (raw):
Between the "-" and the "**" are 4 spaces for Item 1 Level 1 instead of 3.

-    **Item 1 Level 1** 
    -   Item 1 Level 2
    -   Item 2 Level 2
-   Item 2 Level 1

Preview of transformed Markdown result:

Hint: Preview was tested for commonmark on https://babelmark.github.io

Create DITA sections when using "##" in markdown file

If the markdown file looks like this:

# Title
            
Text
            
##another title
            
other content as well

and is referenced in the DITA Map using the "mdita" format that second heading should become a DITA section according to the specs

Section |## or ----- underline

Right now the converted DITA content has the "##" preserved in a paragraph.

DITA publishing to markdown format: Missing Yaml frontmatter?

I have a dita file that contains meta data:

<topic id="id_15b57811221b4d66839fa767f9a173a01">
  <title>Introduction</title>
  <prolog>
    <metadata>
      <keywords>
        <keyword>KEYWORD1</keyword>
        <indexterm>INTRO_INDEX</indexterm>
      </keywords>
    </metadata>
  </prolog>
  <body>Some Test</body>
</topic>`

When I transform the dita file with Option --format=markdown_github the resulting markdown file does not contain any YAML Header.

Is this behaviour expected or is this a bug?

Definition List causes DOM Exception in markdown to dita conversion

I added a definition list to my document and immediately encountered an DOM exception about inserting a node where it is not permitted. Removing the definition list allow the app to succeed.

Here is the problematic document:

# My Title

This is a sample page

Apple
:   Pomaceous fruit of plants of the genus Malus in
    the family Rosaceae.

Hello there. 

## My Section 

> Long quote

Running this through lwdita using a java driver produces the following exception:

Error on line 182 column 3 of specialize.xsl:
  org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node
  where it is not permitted. 
  at xsl:apply-templates (classpath:///specialize.xsl#182)
     processing /topic/title[1]
  at xsl:apply-templates (classpath:///specialize.xsl#30)
     processing /topic
  at xsl:apply-templates (classpath:///specialize.xsl#11)
     processing /topic
org.xml.sax.SAXException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
net.sf.saxon.trans.XPathException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
java.lang.RuntimeException: org.xml.sax.SAXException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
net.sf.saxon.trans.XPathException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
	at com.elovirta.dita.markdown.DitaRenderer$MainNodeRenderer.render(DitaRenderer.java:394)
	at com.elovirta.dita.markdown.DitaRenderer.render(DitaRenderer.java:150)
	at com.elovirta.dita.markdown.MarkdownReader.parseAST(MarkdownReader.java:273)
	at com.elovirta.dita.markdown.MarkdownReader.parse(MarkdownReader.java:184)
	at net.sf.saxon.event.Sender.sendSAXSource(Sender.java:427)
	at net.sf.saxon.event.Sender.send(Sender.java:138)
	at net.sf.saxon.jaxp.IdentityTransformer.transform(IdentityTransformer.java:374)
	at com.elovirta.dita.markdown.Driver.main(Driver.java:57)
Caused by: org.xml.sax.SAXException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
net.sf.saxon.trans.XPathException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
	at net.sf.saxon.jaxp.TransformerHandlerImpl.endDocument(TransformerHandlerImpl.java:174)
	at com.elovirta.dita.markdown.DitaRenderer$MainNodeRenderer.render(DitaRenderer.java:392)
	... 7 more
Caused by: net.sf.saxon.trans.XPathException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
	at net.sf.saxon.dom.DOMWriter.startElement(DOMWriter.java:142)
	at net.sf.saxon.event.TreeReceiver.startElement(TreeReceiver.java:180)
	at net.sf.saxon.event.ReceivingContentHandler.startElement(ReceivingContentHandler.java:310)
	at net.sf.saxon.event.ContentHandlerProxy.startContent(ContentHandlerProxy.java:388)
	at net.sf.saxon.event.NamespaceReducer.startContent(NamespaceReducer.java:213)
	at net.sf.saxon.event.ComplexContentOutputter.startContent(ComplexContentOutputter.java:719)
	at net.sf.saxon.event.ComplexContentOutputter.startElement(ComplexContentOutputter.java:294)
	at net.sf.saxon.expr.instruct.ElementCreator.processLeavingTail(ElementCreator.java:330)
	at net.sf.saxon.expr.instruct.Copy.processLeavingTail(Copy.java:415)
	at net.sf.saxon.expr.instruct.TemplateRule.applyLeavingTail(TemplateRule.java:347)
	at net.sf.saxon.trans.Mode.applyTemplates(Mode.java:502)
	at net.sf.saxon.expr.instruct.ApplyTemplates.apply(ApplyTemplates.java:295)
	at net.sf.saxon.expr.instruct.ApplyTemplates.process(ApplyTemplates.java:248)
	at net.sf.saxon.expr.instruct.ElementCreator.processLeavingTail(ElementCreator.java:337)
	at net.sf.saxon.expr.instruct.Copy.processLeavingTail(Copy.java:415)
	at net.sf.saxon.expr.instruct.TemplateRule.applyLeavingTail(TemplateRule.java:347)
	at net.sf.saxon.trans.Mode.applyTemplates(Mode.java:502)
	at net.sf.saxon.expr.instruct.ApplyTemplates$ApplyTemplatesPackage.processLeavingTail(ApplyTemplates.java:553)
	at net.sf.saxon.Controller.transformDocument(Controller.java:2404)
	at net.sf.saxon.Controller.transform(Controller.java:1970)
	at net.sf.saxon.s9api.XsltTransformer.transform(XsltTransformer.java:596)
	at net.sf.saxon.jaxp.TransformerImpl.transform(TransformerImpl.java:73)
	at net.sf.saxon.jaxp.TransformerHandlerImpl.endDocument(TransformerHandlerImpl.java:172)
	... 8 more
Caused by: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted. 
	at org.apache.xerces.dom.CoreDocumentImpl.insertBefore(Unknown Source)
	at org.apache.xerces.dom.NodeImpl.appendChild(Unknown Source)
	at net.sf.saxon.dom.DOMWriter.startElement(DOMWriter.java:138)
	... 30 more

The source of the driver java application is:

            DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
            builderFactory.setNamespaceAware(true);
            DocumentBuilder db = builderFactory.newDocumentBuilder();
            File testfile = new File("sample.md");
            File result = new File("sample.dita");

            Document act;
            InputStream in = new FileInputStream(testfile);
            OutputStream out = new FileOutputStream(result);
            act = db.newDocument();
            Transformer t = TransformerFactory.newInstance().newTransformer();
            XMLReader r = new MarkdownReader();
            InputSource i = new InputSource(in);
            DOMResult res = new DOMResult(act);
            SAXSource intermediate = new SAXSource(r,i);
            t.transform(new SAXSource(r, i), new DOMResult(act));
            TransformerFactory.newInstance().newTransformer().transform(new DOMSource(act), new StreamResult(out));
        } catch (Exception e) {
            System.err.println(e.getMessage());
            e.printStackTrace();
        }

Markdown transformation to Normalized DITA output generates wrong dtd in xml header

Intention

I want to make use of the tip of the DITA-OT 3.0 release notes:

The dita transformation can also be used to convert Markdown topics or the alternative input formats supported by the org.lwdita plug-in to standard DITA XML

Input

I have a Test.ditamap that references one markdown file that has two headers.

<map>
  <topicref href="test.md" format="markdown"/>
</map>

test.md file:

# Header 1 Level 1
# Header 2 Level 1

DITA command

Transform to Normalized DITA output

"C:\Program Files\DITA-OT\dita-ot-3.0.3\bin\dita" -input=Test.ditamap --format=dita

Result

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "dita.dtd">
<dita>
	<topic id="header-1-level-1">
		<title>Header 1 Level 1</title>
		<body/>
	</topic>
	<topic id="header-2-level-1">
		<title>Header 2 Level 1</title>
		<body/>
	</topic>
</dita>

Expected Result

The referenced dtd should be "ditabase.dtd" instead of "dita.dtd".

<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">

Additional Issue

I get an error where I'm not sure if this should be an error. Isn't it possible to have markdown files
without header level 1?

Change the header level in test.md

## Header 1 Level 2
## Header 2 Level 2

Result in logfile

Failed to parse Markdown: Header level raised from 0 to 2 without intermediate header level

DITA + Markdown publishing fail - "No renderer configured for com.vladsch.flexmark.ext.typographic.TypographicSmarts"

See issue here for more details and samples:
dita-ot/dita-ot#2866

MDITA: code blocks specified by indent don't work right

MDITA files that specify codeblocks by indent don't display right in PDF ouput. (The three backticks construct works OK, which is a good workaround.)

Example input:

---
ID: codeblock
---

# Codeblock test

MDITA can specify codeblocks two different ways.
One is broken.

This works:

```
output codeblocks
everything should be
indented by the same amount
```

Broken:

    output codeblocks
    everything should be
    indented by the same amount

End of test

In the second example, the first line is right but subsequent lines are indented from the first line.

Unable to append HTML content - Java API

Description

While using DITA-OT Java API, I am unable to append HTML content into my PDF, getting below error:

6365 [INFO ] Processing file:/.../ditamapfile/report.html to 
file:/.../javatmp/1562711388902/c6efa7d04b7ef9aa6f47d9f67a8b226ae4362426.html
6366 [ERROR] [DOTJ013E][ERROR] Failed to parse the referenced file 
'file:/.../ditamapfile/report.html'.: com.elovirta.dita.html.HtmlReader

However, if I call dita on the command line this error is not thrown, and the HTML is appended.

I have tried with below ditamap:

...
    <appendix navtitle="Report">
      <topicref format="hdita" href="content.html" locktitle="yes" 
navtitle="Report" scope="local"/>
    </appendix>
    <backmatter>
....

And below JAVA Code:

Processor ditaProcessor = ditaProcessFactory.newProcessor("pdf")
			.setInput(new File("/.../ditamapfile/ip_ii_new.ditamap"))
			.setOutputDir(new File(outputDir))
			.setProperty("args.input", "/.../ditamapfile/ip_ii_new.ditamap")
			.setProperty("org.dita.pdf2.i18n.enabled", "false")
			//.setProperty("args.filter", filterList.toString())
			.createDebugLog(true);

ditaProcessor.run();

I have tried with format equal to html and hdita, and both are giving the same error.

Environment:
MacOs
DITA-OT 3.3.2

Thank you!

Transformation of Markdown files to HTML Help fails

I have a ditamap that contains a DITA file and a Markdown file.

Environment: Windows 10, DITA-OT 3.3.1

When I execute the following command

- Chm / htmlhelp Output with dita-ot 3.3.1
"C:\Program Files\DITA-OT\DitaToolKit\dita-ot-3.3.1\bin\dita" --input=Test.ditamap --output=out\htmlhelp --format=htmlhelp --temp=temp\htmlhelp --logfile=loghtmlhelp.xml --clean.temp=no  --verbose --debug

the DITA file is shown correctly in the chm file, but the markdown file cannot be rendered.
See screenshot:

When I transform it to pdf or markdown the result is correct

- Pdf Output with dita-ot 3.3.1
"C:\Program Files\DITA-OT\DitaToolKit\dita-ot-3.3.1\bin\dita" --input=Test.ditamap --output=out\pdf --format=pdf --temp=temp\pdf --logfile=logpdf.xml --clean.temp=no --verbose --debug

- Markdown_github Output with dita-ot 3.3.3
"C:\Program Files\DITA-OT\DitaToolKit\dita-ot-3.3.1\bin\dita" --input=Test.ditamap --output=out\markdown_github --format=markdown_github --temp=temp\markdown_github --logfile=logmarkdown_github.xml --clean.temp=no --verbose --debug

Attached is also the zip file including the test files, the Test.ditamap and all log/temp/output files.

TestMD2HtmlHelp.zip

Can anyone reproduce this behavior?

no line break between <cmd> and <stepresult> in markdown output

DITA input

<step>
  <cmd>step</cmd>
  <stepresult>result</stepresult>
</step>

is rendered as

1. step result

without any indication of the two being separate things.

Fatal error during transformation using C:\dita-ot-3.1\plugins\org.lwdita\xsl\dita2markdown_github.xsl: In the key() function, the node supplied in the third argument (or the context node if absent) must be in a tree whose root is a document node; SystemID: file:/C:/dita-ot-3.1/plugins/org.lwdita/xsl/dita2markdownImpl.xsl; Line#: 891; Column#: 33

Working through issues converting my dita files into markdown. I'm running the following command:
dita --input=c:\iva_kc_files_dita_and_md\14_customizing_and_extending_the_solution_further\dita\files\customize.ditamap --format=markdown_github --verbose --debug --logfile=errlog

The zip file contains the .dita files, the .ditamap, the 1 .md file that was created and the errlog that was generated.
Dita_to_MD.zip

DITA tables: How do I prevent duplicating topics when the only difference is a table column?

I have to display two tables in two separate documents which essentially contain the same information, but in one of the documents, I have two extra columns. For example:

In Manual A, the table needs to look like:
Name | ID | Description

In Manual B, the table needs to look like:
Name | ID | Description | Code

Is there any clever way of applying the "principles of conkeyrefing" a column in? I know tables are built on a row-basis, but, is there any way I could prevent simply duplicating my content because of a single column?

Nested Lists not properly generated in output Markdown content when Codeblocks And Paragraphs are included

In DITA-OT 3.3 nested Lists are not properly generated in output Markdown content when Codeblocks and Paragraphs are included while transformed to markdown: e.g. some list items are interpreted as codeblock! The codeblocks are also not correctly intended.

DITA xml source
Is included in file TestMdTransformForNestedListWithCodeblocksAndParagraphs.xml in the attached
Test.zip

Markdown result (left side) in comparison to xhtml output (right side is the expected result)

Possible Solution:

Possible changes in file dita-ot-3.3\plugins\org.lwdita\xsl\ast2markdown.xsl are marked with CLARIFY. The modified ast2markdown_clarify.xsl file is also included in the zip.

DITA to various flavors of CommonMark/Markdown

In DITA tables we have a lot of flexibility. For example, we can do this:

<entry colname="col3">
	<p>Generic text here.</p>
	<p>More generic text here. </p>
	<dl compact="yes">
		<dlentry>
			<dt>0</dt>
			<dd><p>There's a lot going on here.</p></dd>
		</dlentry>
		<dlentry>
			<dt>1</dt>
			<dd><p>More content is placed here.</p></dd>
		</dlentry>
	</dl>
	<p>More explanation goes here.</p>
</entry>

To be fair, this falls within the CommonMark/Markdown limitations. But what I would hope to get out is a table with some representation of that data. However, that's not what happens. I end up with a table entry that has the first paragraph item in it, then the table pretty much breaks at that point and the remaining content is placed in the file, but not in the table.

Possible Solution (enhancement)

Multiple lines are extremely hard to deal with in Markdown tables. In fact, the only solution I know of is to make tables HTML tables instead of MD text.

YAML header causes error message: Error: Failed to run pipeline: No renderer configured for com.vladsch.flexmark.ext.jekyll.tag.JekyllTagBlock

When I set my dita map topicref format attributes to markdown, I get the following error:

Error: Failed to run pipeline: No renderer configured for com.vladsch.flexmark.ext.jekyll.tag.JekyllTagBlock

After our email conversation, it was determined that this was caused by the YAML header in the files. When I removed the YAML headers, the files built fine.

This error occurred using DITA-OT 3.2.

Better handling for Markdown line-through

For a Markdown file which looks like this:

        # Title
        
        Text ~~some strike through content~~ sdasd

the corresponding converted DITA element for the strike through is a "ph" with status="deleted". Instead it should be a "line-through" element:

http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part2-tech-content/langRef/base/line-through.html

Move plugin as part of the dita-ot organization

As this plugin is now a part of the DITA OT installation maybe it could be moved on GitHub to be part of the DITA OT organization.

Support for conversions to LightWeight DITA Map

In the specs there seems to be an example of an "MDITA Map":

http://docs.oasis-open.org/dita/LwDITA/v1.0/cnprd01/LwDITA-v1.0-cnprd01.html#example-of-an-mdita-map

Maybe if in the main DITA Map you have a topicref like this:

 <topicref href="map.md" format="mditamap"/>

you could have an extra parser to convert that to a LightWeight DITA Map.

oasis-tcs/dita#308

Tasks labels are not generated for Markdown output

In DITA-OT 3.2.1 tasks labels are not generated. The args.gen.task.lbl parameter is set to "YES".
DITA xml source:

 <task id="task_1">    
    <title>Task</title> 
    <shortdesc>Short description</shortdesc>
    <taskbody>
      <prereq>
        <ol>
          <li>
            First Prerequisites.
          </li>
          <li>
            Second Prerequisites.
          </li>
        </ol>
      </prereq>
      <steps>
        <step>
          <cmd>Do the first step</cmd>
          <stepresult>Result of first step</stepresult>
        </step>
        <step>
          <cmd>Do the second step</cmd>
          <stepresult>Result of second step</stepresult>
        </step>
      </steps>
      <postreq>Result of Postrequisites</postreq>
    </taskbody>
  </task>

Markdown result when transformed with markdown:

# Task {#task_1 .task}
Short description

1.  First Prerequisites.
2.  Second Prerequisites.

1.   Do the first step Result of first step
2.   Do the second step Result of second step

Result of Postrequisites

Displayed result when transformed with xhtml (Expected Result):

Feature request: troubleshooting topics

Supporting troubleshooting topics would be a useful addition. It might work like this:

# Troubleshooting something {.troubleshooting}

optional shortdesc

## some title {.condition}

If the title is blank, use the default heading.

## some title {.cause}

ditto

## some title {.remedy}

ditto

The cause and remedy sub-sections could be repeated if necessary. If the sub-section titles are blank (for example, ## {.condition}, use the default titling for those sections.

Incorrect error: Header level raised from 1 to 3 without intermediate header level

I have a Markdown file like this:

         # Header 1
        
        This is a quote:
        
        ## Header 2
        
        List sample:
        
        ### Header 3
        
        Table sample.

It's conversion to "mdita" yields the error:

           Header level raised from 1 to 3 without intermediate header level

but there is no such problem in the Markdown which properly increases the header level.

mdita typed topic doesn't work

Issue Summary

When I use format type "mdita", typed topic tag like {.concept} does not work well.

If I use it with format type "markdown", it works well, but in the README, format type "markdown" was not mentioned. So, I guess I should not use "markdown" format and should use "mdita", but I could not find how to convert these differences.

Detail

DITA-OT version is 3.2 on Mac OS Mojave.

I have the following map.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">

<map>
  <title>Working in the garage</title>
  <topicref href="template-task.md" format="markdown" />
  <topicref href="template-concept.md" format="mdita" />
</map>

And template-task.md and template-concept.md are the followings:

template-task.md

---
keyword:
  - task
---

# Title of Task {.task}
Task context description.

The followings are the steps.

1. steps1

    step1 content

2. steps2

    step2 content

template-concept.md

---
keyword:
  - task
---

# Title of Concept {.concept}
Concept context description.

And I ran the following command:

dita --input="template-map.ditamap" --output="out" --format html5

After ran it, index.html shows the following:

Working in the garage
    ・Title of Task
    ・Title of Concept {.concept}
    ・Title of Reference

As you can see, template-concept, which I set the format="mdita", shows raw characters and it looks did not work as expected. In the other hand, template-task, which I set the format="markdown", looks work as expected.

Also if I use reltable in map file, concept was processed "Related information", but task was processed "Related tasks".
It obviously shows format="mdita" could not process typed topic in this way.

Is there any solution?
Should I use format type "markdown" or "mdita"?

If I add a line break after I end the last line of text with two spaces I should get a new paragraph

Moving this issue:
https://github.com/jelovirt/dita-ot-markdown/issues/60
to the new plugin.

This small Markdown content should be interpreted as two paragraphs because the first line of text ends with two spaces.

some words  
other words

See:

https://daringfireball.net/projects/markdown/syntax#p

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Of course with DITA there is no "br" but we should probably create a new paragraph for it.

Markdown to DITA breaks when using inline HTML elements

For a Markdown file like this:
Unbenannt1.zip

The conversion throws an error like:

      No renderer configured for com.vladsch.flexmark.ext.aside.AsideBlock

Referencing Markdown file with "mdita" format should produce LightWeight DITA topic equivalent

Let's say I refer in the DITA Map to this markdown file using the "mdita" format:

# Title

Text
dasdas
            
dasdas

| Tables   |      Are      |  Cool |
|----------|:-------------:|------:|
| col 1 is |  left-aligned | $1600 |
| col 2 is |    centered   |   $12 |
| col 3 is | right-aligned |    $1 |

The equivalent DITA topic generated in the "temp" folder should be a lightweight DITA topic, it should have the proper "domains" attribute value plus the table should be a "simpletable" because the LwDITA specs does not support cals tables.

Images in Tasks are interpreted as codeblock for Markdown output

In DITA-OT 3.2.1 images in tasks get indented while transformed to markdown and consequently are displayed as codeblock.
DITA xml source:

<task id="task">
  <title>Task </title>
  <taskbody>
    <context>
      <p>Context</p>
    </context>
    <steps>
      <step>
        <cmd>Command</cmd>
        <info>
          <p>Info start.</p>
	  <p><image href="Markdown.png"><alt>Alt</alt></image></p>
	  <p>Info end.</p>
        </info>
      </step>
    </steps>
  </taskbody>
</task>

Markdown result when transformed with markdown:

Task {#task .task}

Context

1. Command

Info start.

![Alt](Markdown.png).

Info end.

Expected Result:

Add possibility to specif image width or scale

Sometimes images included in Markdown content are larger and they need to be scaled. So somehow we would need to specify the equivalent of the DITA @width or @scale attributes in the Markdown content.

Problem with formats supported by LWDita plugin

The plugin.xml declares the following format parsers:

   <parser format="html" class="com.elovirta.dita.html.HtmlReader"/>
  <parser format="hdita" class="com.elovirta.dita.html.HtmlReader"/>

Two possible problems:

1. Shouldn't the "hdita" format use the "HDitaReader" instead of "HtmlReader"?

2. I do not quite agree that the "html" DITA format should be automatically handled by this plugin.
   For example if in my topic I have a reference to some HTML document from my project:

    <p><xref format="html" href="test.html"/></p>
   

why should it be parsed as a DITA topic? Maybe I want to keep this HTML document separate from my PDF and I just want to refer to it. And now I have no control over this behavior, I need to comment out parts of the plugin and run the integrator to remove this automatic handling of the "html" format.
How about if we just add the processor on some specific format like "htmlDita" which would mark that we want the HTML to be interpreted as DITA?

Update flexmark to 0.32.24

Update flexmark dependency to version 0.32.24

Add some possibility to create DITA superscript (sup) and subscript (sub) elements

Maybe using "^" and "~" to surround those pieces of text.
Something like:

      32^nd^ H~2~O

Flexmark license is BSD, not Apache 2.0

Feedback from our legal:

1. The file org.lwdita/blob/master/licenses/flexmark-license.txt should include the contents from https://github.com/vsch/flexmark-java/blob/master/LICENSE.txt (because right now it has an Apache 2.0 license included).
2. The file "https://github.com/jelovirt/org.lwdita/blob/master/NOTICES" should specify BSD 2.0 for flexmark instead of Apache 2.0.

XSLT Error: Unsupported AST nodes link/cite

Generating GitBook output for the DITA-OT docs throws XSLT errors:

[xslt] ERROR: Unsupported AST node link
[xslt] ERROR: Unsupported AST node cite

Steps to reproduce

In the docsrc/ directory, run dita --input=userguide.ditamap --format=markdown_gitbook.

Conrefs work when generating DITA but not PDF, keys not at all

Environment: MacOS Mojave, DITA-OT 3.1, and lwdita.org 2.0.6.

I've attached a minimal example of a map, a content topic, and a collection-of-snips topic. The latter contains a conref paragraph and a shortcut reference link.

When converting to DITA with dita --input=reusetest.ditamap --format=dita, the conref'ed paragraph appears in the output, but not the shortcut.

When publishing to PDF with dita --input=reusetest.ditamap --format=pdf, neither the conref'ed paragraph nor the shortcut appear in the PDF.

con_test.zip

Failed to run pipeline: Failed to merge map

main2.zip

Hi. I included this issue as part of #14 when I should have created a new issue. Sorry.

I've included my entire set of files to give you better context for what I'm experiencing. Hopefully this is OK. I've been commenting out my map in order to isolate other bugs. If you take a look in the file how-do-i-duplicate-my-store.md, line 55 is causing the error:

Error: Failed to run pipeline: Failed to merge map C:\ditaout\shopify_temp\C:\d3\shopify\main2.ditamap: C:\ditaout\shopify_temp\C:\d3\shopify\main2.ditamap (The filename, directory name, or volume label syntax is incorrect)

It seems to be related to both links in that sentence:

Orders can **not** be imported into a store through the Shopify admin, but they **can** be imported through the [Shopify API](/api). **This is not supported by Shopify**. We recommend visiting [our Shopify Experts marketplace](/experts.shopify.com) to find a developer for hire if you must import orders into the new store.

When I remove both links, the file builds.

I get this same error on multiple files in this map.

lwDITA fails on MDITA files with URLs outside of links

Free-floating URLs, those outside Markdown links, trigger exceptions. This is a lot like the (resolved) Issue #3. I used DITA-OT 3.0, but updated the lwDITA plugin to 2.0.2.

With URLs inside angle brackets, like http://dita-ot.org/, lwDITA fails with "No renderer configured for AutoLink"

With URLs without the angle brackets, like http://dita-ot.org/, lwDITA fails with "No renderer configured for TextBase"

An URL inside a link, like the attachment below, is OK.

I've attached a zip with a map and MDITA files, about as simple an example as you can get:
broken.zip

No possibility to create the equivalent of a DITA table with a title

For images you can specify a title and the corresponding DITA topic will have a figure:

https://github.com/jelovirt/dita-ot-markdown/wiki/Syntax-reference#images

Ideally we would have some similar way of doing this to specify a title for the Markdown table and have that converted to a DITA table containing a title.

XSLT Error: Unsupported AST node subscript/superscript for DITA publishing to markdown_github format

I have a dita file that contains superscripts and subscript
(see https://www.oxygenxml.com/dita/1.3/specs/langRef/base/sub.html )

GitHub Flavored Markdown supports the tags <sub> and <sup>.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<dita>
  <topic id="id_40a72787efc94c2a8bb6e60f8cac2b2c">
	<title>Test</title>
	<shortdesc>Test element <i>sub</i> and <i>sup</i></shortdesc>
	<body>
		<p>
		This is some testsub<sub>1</sub> and testsup<sup>2</sup>.
		</p>
	</body>
  </topic>
</dita>

When I transform with DITA-OT 3.1 the dita file with Option --format=markdown_github
I get an xslt error in the logfile:

     [xslt] ERROR: Unsupported AST node subscript
     [xslt] ERROR: Unsupported AST node superscript

Result looks like:

Result begin:

Test

Test element sub and sup

This is some testsub1 and testsup2.

Result end

Expected output should look like:

Expected begin:

Test

Test element sub and sup

This is some testsub₁ and testsup².

Expected end:

Is it possible that this also can be supported?

Use HDITA reader for `hdita` format

Use HDITA reader for hdita format in reader configuration.

Format attribute not properly computed for link to markdown file

I have two markdown files referenced in the DITA Map, both with "format='markdown'".
Let's say in a Markdown file I have a link to another markdown file:

        [Some text here](../src/referencedTopic.md#idValue).

the generated DITA content will look like this:

      <xref
                href="../src/referencedTopic.md#idValue"
                format="md#idValue">Some text here</xref>

and because the anchor was not stripped from the format attribute value the "referencedTopic.md" will be considered as having html format in the ".job.xml" and not being copied to the temporary folder.