Using markdown files for WebHelp transformation?

Hav09
Posts: 3

Using markdown files for WebHelp transformation?

Fri Jun 23, 2017 11:19 pm

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
Posts: 5221

Re: Using markdown files for WebHelp transformation?

Mon Jun 26, 2017 8:20 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
Hav09
Posts: 3

Re: Using markdown files for WebHelp transformation?

Mon Jun 26, 2017 8:42 pm

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
Posts: 5221

Re: Using markdown files for WebHelp transformation?

Tue Jun 27, 2017 8:54 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Return to “DITA (Editing and Publishing DITA Content)”

Who is online

Users browsing this forum: No registered users and 2 guests