60 lines
No EOL
8.7 KiB
HTML
60 lines
No EOL
8.7 KiB
HTML
<!DOCTYPE html
|
||
SYSTEM "about:legacy-compat">
|
||
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="generator" content="DITA-OT"><meta name="description" content="Markdown is a lightweight markup language that allows you to write using an easy-to-read plain text format and convert to structurally valid markup as necessary."><meta name="keywords" content=", format, authoring formats, Markdown, CommonMark, converting lightweight formats to DITA"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Markdown content</title></head><body id="markdown-input"><header role="banner"><div class="header">
|
||
<p>DITA Open Toolkit</p>
|
||
<hr>
|
||
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.6</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../topics/input-formats.html">Authoring formats</a><ul><li><a href="../topics/dita-xml-input.html">Standard DITA XML</a></li><li class="active"><a href="../topics/markdown-input.html">Markdown content</a></li><li><a href="../topics/lwdita-input.html">Lightweight DITA</a></li><li><a href="../topics/markdown-dita-syntax-reference.html">Markdown DITA syntax</a></li></ul></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
|
||
<h1 class="title topictitle1" id="ariaid-title1">Markdown content</h1>
|
||
|
||
|
||
<div class="body"><p class="shortdesc">
|
||
<a class="xref" href="https://daringfireball.net/projects/markdown/" target="_blank" rel="external noopener">Markdown</a> is a lightweight markup language that allows you to write using an easy-to-read plain text
|
||
format and convert to structurally valid markup as necessary.</p>
|
||
<p class="p">In the words of its creators:</p>
|
||
|
||
<blockquote class="lq">“The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is
|
||
that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been
|
||
marked up with tags or formatting instructions.”</blockquote>
|
||
|
||
<p class="p">DITA Open Toolkit now allows you to use Markdown files directly in topic references and export DITA content as
|
||
Markdown.</p>
|
||
|
||
<p class="p">These features enable lightweight authoring scenarios that allow subject matter experts to contribute to DITA
|
||
publications without writing in XML, and support publishing workflows that include DITA content in Markdown-based
|
||
publishing systems.</p>
|
||
|
||
<section class="section"><h2 class="title sectiontitle">Adding Markdown topics</h2>
|
||
|
||
<p class="p">To add a Markdown topic to a DITA publication, create a topic reference in your map and set the
|
||
<code class="keyword markupname xmlatt">@format</code> attribute to <code class="ph codeph">markdown</code> so the toolkit will recognize the source file
|
||
as Markdown and convert it to DITA:</p>
|
||
<div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><?xml version="1.0" encoding="utf-8"?>
|
||
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
|
||
<map>
|
||
<topicref href="markdown-dita-topic.md" <strong class="ph b">format="markdown"</strong>/>
|
||
</map></code></pre></div>
|
||
<p class="p">The <code class="ph codeph">markdown</code> format uses a relatively lenient document parsing approach to support a wide
|
||
range of content and Markdown syntax constructs.</p>
|
||
<div class="note note note_note"><span class="note__title">Note:</span> The Markdown support is based on
|
||
<a class="xref" href="http://commonmark.org" target="_blank" rel="external noopener">CommonMark</a>, a strongly defined, highly compatible specification of Markdown.</div>
|
||
<p class="p">When you add Markdown topics to a DITA publication as described above, the content is temporarily converted to
|
||
DITA in the background when generating other output formats like HTML or PDF, but the Markdown source files
|
||
remain unchanged.</p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> This approach is recommended in cases where simple content is authored collaboratively over
|
||
multiple versions, as Markdown topics can be edited by a wide range of authors and combined as necessary with
|
||
more complex content maintained in DITA XML.</div>
|
||
</section>
|
||
<section class="section"><h2 class="title sectiontitle">Converting Markdown to DITA</h2>
|
||
|
||
<p class="p">In cases where the Markdown input is a one-off contribution, members of the DITA authoring team can use the
|
||
Markdown file as raw material that is easily converted to DITA and enriched with conditional processing
|
||
attributes, conkeyrefs or other more complex semantics that have no equivalent in limited formats like
|
||
Markdown.</p>
|
||
<p class="p">If you prefer to maintain this content in DITA in the future, you can generate DITA output by passing the
|
||
<span class="keyword parmname">--format</span>=<span class="keyword option">dita</span> option on the command line.</p>
|
||
<p class="p">This converts all input files (both DITA XML and Markdown) to
|
||
<a class="xref" href="dita2dita.html" title="The dita transformation generates normalized topics and maps from DITA input. The normalized output includes the results of DITA Open Toolkit pre-processing operations, which resolve map references, keys, content references, code references and push metadata back and forth between maps and topics.">Normalized DITA</a>. You can then copy the generated DITA files from the output
|
||
folder to your project and replace references to the Markdown topics with their DITA equivalents.</p>
|
||
</section>
|
||
</div>
|
||
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/input-formats.html" title="In addition to standard DITA XML, DITA-OT supports several alternative input formats, including Markdown and the proposed XDITA, MDITA and HDITA authoring formats currently in development for Lightweight DITA.">Authoring formats</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/dita-xml-input.html" title="DITA Open Toolkit supports all released versions of the OASIS DITA specification, including 1.0, 1.1, 1.2, and 1.3. As of release 3.6, DITA-OT also provides an initial preview of features for the latest draft of the upcoming DITA 2.0 standard.">Standard DITA XML</a></li><li class="linklist"><a class="link" href="../topics/lwdita-input.html" title="DITA-OT provides preview support for the authoring formats proposed for Lightweight DITA, or “LwDITA”. The XDITA, MDITA and HDITA formats are alternative representations of DITA content in XML, Markdown and HTML5.">Preview support for Lightweight DITA</a></li><li class="linklist"><a class="link" href="../topics/markdown-dita-syntax-reference.html" title="Markdown DITA uses CommonMark as the underlying markup language.">Markdown DITA syntax reference</a></li><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Markdown_plugin" target="_blank" rel="external noopener" title="This talk introduces Jarno Elovirta’s DITA-OT Markdown plugins, which extend the DITA Open Toolkit so you can use Markdown files directly in topic references and export existing DITA content in Markdown format for use in other publishing systems. This makes it easier for people to contribute content to DITA publications, enables mobile authoring workflows, facilitates review processes with less technical audiences and expands the range of publishing options to workflows based on Markdown.">Markdown plugin</a></li></ul></div></nav></article></main></body></html> |