integrating markdown into your dita 1.3 pipeline
TRANSCRIPT
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
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 ([email protected]) - Secretary: Stan Doherty ([email protected])
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/)