Using markdown files for WebHelp transformation?

[Hav09]

Hi I have a license for Oxygen XML Editor and create transformations for PDF, WebHelp Classic, and WebHelp Responsive (fyi, we haven't released doc to customers yet but likely we'll release as PDF and a WebHelp version). My developers create API reference content in markdown as a series of MD files. Rather than copy-pasting to Oxygen to include in my project, I want to be able to include the MD files as written. I've successfully created PDFs which include the MD content and they look great.
I haven't been able to get the MD content to appear in my WebHelp transformations. The WebHelp shows the MD topics as blank pages. I've tired exporting to HTML and including those in the project and they don't appear in the output either.
I'm wondering if there's another trick to getting MD topics to appear in my WebHelp output? OR, must I be using a Oxygen XML WebHelp license to make this happen?
Thanks for your help. Linda

[Radu]

Hi Linda,

What version of Oxygen are you using?
If you are publishing DITA content with Oxygen 18.1 or 19.0 with the DITA Open Toolkit publishing engines bundled with them you can refer in your DITA Map directly to the Markdown files directly like this:

Code: Select all

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

and the publishing engine should automatically treat them as DITA resources.

Regards,
Radu

[Hav09]

Hi Radu
Thanks for your reply. I'm using v19.
I copied 3 MD files from the Garage sample to my project location, and added them to my .ditamap.

I modified my install guide .ditamap to include them, using the references from the garage.ditamap:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
<title><ph keyref="installBook1_name"/></title>
<topicref href="c_install1_preface.dita" print="printonly">
<topicref href="preface2" print="printonly"/>
</topicref>
<topicref href="c_install_intro.dita"/>
......
<topicref href="c_concept1.dita">
<topicref href="t_task1.dita"/>
</topicref>
</topicref>
<topicref href="c_knowledgebase_for_myCompany.dita"/>
<topicref href="carMaintenance.md" format="markdown"/>
<topicref href="changingtheoil.md" format="markdown"/>
<topicref href="washingthecar.md" format="markdown"/>
<topicref href="keys.ditamap" format="ditamap"/>
</map>
The PDF prints with those MD files but still the WebHelp shows empty topics/pages.
What am I missing? I don't have a reltable. Do I need one?
Linda

[Radu]

Hi Linda,

If you look inside the "washingthecar.md" that you copied over to your project, it has a reference to an image and the image was not copied. You can remove that image reference and then publish or copy the image to your project and modify the reference to it so that it's properly referenced.
Sometimes when you have references to resources outside of the folder where the main DITA Map is located the publishing engine may get confused so you should avoid this situation.

Regards,
Radu