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 [email protected]

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


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 ([email protected]) - Secretary: Stan Doherty ([email protected])


Background: DITA and Markdown


First off . . .

. . . all available to download . . .

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


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.


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.


Markdown OASIS DITA

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


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.


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


OASIS DITA and MarkdownRigor/ScalabilityAuthoring/Collaboration

Lightweight

DITA-OTParser

What's good enough?


Tutorial: Setting Up a DITA-Markdown Environment


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

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



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



2. Download and install the latest DITA Open Toolkit.

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



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



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.



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


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>


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


DITA-Markdown Integration Scenarios


Integration ScenariosRigor/ScalabilityAuthoring/Collaboration

SCENARIO - 1Integrate MD

topics as "blobs"


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>




topics as "blobs"

SCENARIO - 2Integrate MD content from

API frameworks

Integration Scenarios


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.


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>




topics as "blobs"


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



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>


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

swagger




topics as "blobs"


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

SCENARIO - 4Round-trip DITA

content for MDcollaboration



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


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)


Resources


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/)

Integrating Markdown Into Your DITA 1.3 Pipeline

Technology

Transcript of Integrating Markdown Into Your DITA 1.3 Pipeline