We would like to have a single location (AEM) for our content. We want to author in DITA and then export/convert the DITA to markdown for use in our GitHub documentation. Also, we would like to import some of our markdown docs into AEM and convert them to DITA so that we no longer need to manage the content in two source systems and use two different markup languages.
XML documentation uses DITA-OT internally to generate the different output. DITA-OT allows the markdown files generation from source dita content and it also lets the author use the raw markdown files for publishing. Please refer below for more details:
Generating Markdown files from the source DITA files
DITA-OT provides three variety of markdown files
GitHub-Flavored Markdown Files
GitHub-Flavored Markdown Files with summary.md file
All the above markdown files types are supported by DITA-OT and can be generated from the XML Documentation Solution by using the relevant transtype. Example – To generate GitHub-Flavored Markdown files, use the markdown_github transtype on the output-preset.
Using Markdown down files for generating output
There is a provision to use the markdown files with the maps and generate the PDF/pre-processed DITA/HTML5 output. There would two things required:
To add a Markdown topic to a DITA publication, create a topic reference in your map and set the @format attribute to markdown so the toolkit will recognize the source file as Markdown and convert it to DITA. More information can be referred here - https://www.dita-ot.org/dev/topics/markdown-input.html
Example - <topicref href="markdown-dita-topic.md" format="markdown"/>
Then you can generate any supported output format e.g. PDF or dita (for normalized dita)
If you need more details OR wanted to discuss your specific use case then please reach out to TechCommSales@adobe.com for a quick demo.