integrating markdown into your dita 1.3 pipeline

Adoption Technical CommitteeAdoption Technical Committee

Integrating Markdown Into Your DITA 1.3 Pipeline

CIDM WebinarJuly 20, 2017

Stanley Doherty, Ph.D. OASIS DITA Adoption Technical Committee

HPE SimpliVityStan@ModularWriting.com

Adoption Technical Committee

Agenda

Background: OASIS DITA and Markdown

Tutorial: Setting Up a Markdown-DITA Environment - Installing the Java SDK - Installing the DITA Open Toolkit - Installing Jarno Elovirta's Markdown Parser Plugin - Processing Markdown topics with the DITA-OT

DITA-Markdown Integration Scenarios - Integrating MD topics as "blobs" - Integrating MD content from API frameworks - Developing MD content that is DITA-aware - Round-tripping DITA content for MD-based collaboration

Resources

Adoption Technical Committee

OASIS DITA Adoption Technical Committee

The DITA Adoption TC focuses on promoting the adoption of the OASIS DITA standard. - Develops learning materials (whitepapers, webinars). - Hosts the dita.xml.org portal for "All Things DITA". - Organizes "listening sessions" to collect feedback from organizations considering DITA, adopting DITA, and extending its capabilities.

- Identifies opportunities to reduce barriers to adoption.

Web resources - http://oasis-open.org - http://dita.xml.org

People contacts - Chair: Keith Schengili-Roberts (keith.roberts@ixiasoft.com) - Secretary: Stan Doherty (stan@modularwriting.com)

Adoption Technical Committee

Background: DITA and Markdown

Adoption Technical Committee

First off . . .

. . . all available to download . . .

http://modularwriting.com/downloads/cidm-markdown-webinar.zip

Adoption Technical Committee

Markdown OASIS DITA

Formal standard maintained by a public standards body (OASIS).

Version 1.0 released in 2005.

XML-only – DTDs, parsers, validation, content/styling separation.

Extensibility within the DITA vocabularity.

Scalability.

Information typing.

Semantic markup.

Translation support.

Rigorous authoring environment.

Developed by John Gruber to simplify the HTML authoring.

Version 1.0 released in 2005.

Well-formed document parsing.

No separation of content and styling.

Extensibility via support for HTML, JavaScript, YAML, JSON, and others.

Robust integration with multiple API and engineering development frameworks.

Lightweight format – simple, easy-to-learn markup syntax.

Adoption Technical Committee

Markdown OASIS DITA

Formal standard maintained by a public standards body (OASIS).

Version 1.0 released in 2005.

XML-only – DTDs, parsers, validation, content/styling separation.

Extensibility within the DITA vocabularity.

Scalability.

Information typing.

Semantic markup.

Translation support.

Rigorous authoring environment.

Developed by John Gruber to simplify the HTML authoring.

Version 1.0 released in 2005.

Well-formed document parsing.

No separation of content and styling.

Extensibility via support for HTML, JavaScript, YAML, JSON, and others.

Robust integration with multiple API and engineering development frameworks.

Lightweight format – simple, easy-to-learn markup syntax.

Rigor/ScalabilityAuthoring/Collaboration

Adoption Technical Committee

OASIS DITA and MarkdownRigor/ScalabilityAuthoring/Collaboration

Lightweight

DITA-OTParser

What's good enough?

Adoption Technical Committee

Tutorial: Setting Up a DITA-Markdown Environment

Adoption Technical Committee

Tutorial - setting it all up1. Download and install the latest Java SDK.

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

Adoption Technical Committee

Tutorial - setting it all up1. Download and install the latest Java SDK.

2. Download and install the latest DITA Open Toolkit.http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

http://www.dita-ot.org/download

Adoption Technical Committee

Tutorial - setting it all up1. Download and install the latest Java SDK.

2. Download and install the latest DITA Open Toolkit.

3. Download and install Jarno Elovirta's Markdown plugin.

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

http://www.dita-ot.org/download

c:\dita-ot-2.5.1\bin\dita -install \https://github.com/jelovirt/dita-ot-markdown/releases/download/ \1.3.0/com.elovirta.dita.markdown_1.3.0.zip

https://github.com/jelovirt/dita-ot-markdown

Adoption Technical Committee

Tutorial - setting it all up1. Download and install the latest Java SDK.

2. Download and install the latest DITA Open Toolkit.

3. Download and install Jarno Elovirta's Markdown plugin.

4. Integrate the Markdown plug-in with the DITA-OT.

5. Review Jarno's documentation.

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

http://www.dita-ot.org/download

c:\dita-ot-2.5.1\bin\dita -install \https://github.com/jelovirt/dita-ot-markdown/releases/download/ \1.3.0/com.elovirta.dita.markdown_1.3.0.zip

https://github.com/jelovirt/dita-ot-markdown

c:\dita-ot-2.5.1\bin\dita -install

Adoption Technical Committee

Tutorial - setting it all up6. Create two test files in a local folder (md-test).

md_topic1.md

# Sample Markdown Topic

This topic serves to test the Markdown parser. Markdown supports the following basic blocks:

* Lists (ordered and unordered) * Tables * Block quotes * Code blocks

``` function test() {

console.log("Hello, world"); } ``` Pretty basic, **right**?

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

<title>Markdown Test Map</title> <topicref href="md_topic1.md" format="markdown"/>

</map>

Adoption Technical Committee

Tutorial - setting it all up7. Generate a PDF from the new DITA map.

8. View the generated PDF.

c:\dita-ot-2.5.1\bin\dita \-i c:\dita-ot-2.5.1\docsrc\markdown\md-test\dita_map1.ditamap \-f pdf \ -o c:\dita-ot-2.5.1\docsrc\markdown\output\md-test

Adoption Technical Committee

DITA-Markdown Integration Scenarios

Adoption Technical Committee

Integration ScenariosRigor/ScalabilityAuthoring/Collaboration

SCENARIO - 1Integrate MD

topics as "blobs"

Adoption Technical Committee

Integration Scenarios – MD "Blobs"Sometimes you need to ingest MD topics "owned" by external partners, other product groups, or subcontractors.

<topichead navtitle="USE CASE #1 - Import Markdown as Content Blobs"> <topicref href="github_markdown-plugin.md" format="markdown"/> <topicref href="github_json-to-markdown.md" format="markdown"/>

</topichead>

Adoption Technical Committee

Rigor/ScalabilityAuthoring/Collaboration

SCENARIO - 1Integrate MD

topics as "blobs"

SCENARIO - 2Integrate MD content from

API frameworks

Integration Scenarios

Adoption Technical Committee

Integration Scenarios – API Content in MDThe API frameworks used by many Engineering organizations speak fluent MD. Extracting or reusing that MD content for API documentation in DITA is a big deal.

Adoption Technical Committee

Integration Scenarios – API Content in MDThe API frameworks used by many Engineering organizations speak fluent MD. Extracting or reusing that MD content for API documentation in DITA is a big deal.

<topichead navtitle="USE CASE #2 - Extract and Integrate API Content in Markdown"> <topicref href="test.dita" format="dita"/> <topicref href="swaggerui_markdown.md" format="markdown"/>

</topichead>

Adoption Technical Committee

Rigor/ScalabilityAuthoring/Collaboration

SCENARIO - 1Integrate MD

topics as "blobs"

SCENARIO - 2Integrate MD content from

API frameworks SCENARIO - 3Develop MD content that is DITA-aware

Integration Scenarios

Adoption Technical Committee

Integration Scenarios – DITA-aware MDEven though the in-topic content is lightweight, you can wrapper the MD topics in some medium-weight map metadata.

<topicref href="concept.md" format="markdown" product="basic"> <topicmeta>

<audience type="smart"/> <othermeta name="conceptual" content="yes"/><othermeta name="product" content="TheThing"/>

</topicmeta> </topicref><topicref href="reference.md" format="markdown" product="intermediate">

<topicmeta> <audience type="wicked-smart"/> <othermeta name="reference" content="yes"/> <othermeta name="product" content="TheThing"/>

</topicmeta></topicref>

Adoption Technical Committee

Integration Scenarios – DITA-aware MDJarno's Markdown parser also supports extensions that enhance integration with DITA keys, topic types, and markup. MD templates!!

swagger

Adoption Technical Committee

Rigor/ScalabilityAuthoring/Collaboration

SCENARIO - 1Integrate MD

topics as "blobs"

SCENARIO - 2Integrate MD content from

API frameworks SCENARIO - 3Develop MD content that is DITA-aware

SCENARIO - 4Round-trip DITA

content for MDcollaboration

Integration Scenarios

Adoption Technical Committee

Integration Scenarios – Roundtrip DITA MDSometimes . . . we need to move our DITA content out of the ivory tower let it play freely with the other kids (content developers). The Markdown parser lets you transform DITA domains into three flavors of MD.

c:\dita-ot-2.5.1\bin\dita \-i c:\dita-ot-2.5.1\docsrc\samples\hierarchy.ditamap \-o c:\dita-ot-2.5.1\docsrc\markdown\output\export2markdown \-f markdown

CommonMark MD

c:\dita-ot-2.5.1\bin\dita \-i c:\dita-ot-2.5.1\docsrc\samples\hierarchy.ditamap \-o c:\dita-ot-2.5.1\docsrc\markdown\output\export2markdown \-f markdown_github

GitHub MD

c:\dita-ot-2.5.1\bin\dita \-i c:\dita-ot-2.5.1\docsrc\samples\hierarchy.ditamap \-o c:\dita-ot-2.5.1\docsrc\markdown\output\export2markdown \-f markdown_gitbook

GitBook MD

Adoption Technical Committee

Integration Scenarios – Roundtrip DITA MDSometimes . . . we need to move our DITA content out of the ivory tower let it play freely with the other kids (content developers). The Markdown parser lets you transform DITA domains into three flavors of MD.

c:\dita-ot-2.5.1\bin\dita \-i c:\dita-ot-2.5.1\docsrc\samples\hierarchy.ditamap \-o c:\dita-ot-2.5.1\docsrc\markdown\output\export2markdown \-f markdown

CommonMark MD

c:\dita-ot-2.5.1\bin\dita \-i c:\dita-ot-2.5.1\docsrc\samples\hierarchy.ditamap \-o c:\dita-ot-2.5.1\docsrc\markdown\output\export2markdown \-f markdown_github

GitHub MD

c:\dita-ot-2.5.1\bin\dita \-i c:\dita-ot-2.5.1\docsrc\samples\hierarchy.ditamap \-o c:\dita-ot-2.5.1\docsrc\markdown\output\export2markdown \-f markdown_gitbook

GitBook MD

# Working in the garage

- [Garage Tasks](tasks/garagetaskoverview.md)- [Changing the oil in your car](tasks/changingtheoil.md)- [Organizing the workbench and tools](tasks/organizing.md)- [Shovelling snow](tasks/shovellingsnow.md)- [Spray painting](tasks/spraypainting.md)- [Taking out the garbage](tasks/takinggarbage.md)- [Washing the car](tasks/washingthecar.md)

- [Garage Concepts](concepts/garageconceptsoverview.md)- [Lawnmower](concepts/lawnmower.md)

Adoption Technical Committee

Resources

Adoption Technical Committee

Resources

Markdown flavors - CommonMark (http://commonmark.org/) - GitHub-Flavored Markdown (https://github.github.com/gfm/) - MultiMarkdown (http://fletcherpenney.net/multimarkdown/)

Conversion tools - Pandoc (https://pandoc.org/)

Markdown editors - MarkdownPad (http://markdownpad.com/) - SublimeText (https://www.sublimetext.com/)

Assembly/delivery tools - Jekyll (https://github.com/jekyll) - GitBook (https://www.gitbook.com/)

API frameworks - OpenAPI/SwaggerUI (https://swagger.io/swagger-ui/) - API BluePrint (https://apiblueprint.org/) - RAML - TESTful API Modeling Language (https://raml.org/)