361 lines
No EOL
22 KiB
HTML
361 lines
No EOL
22 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 DITA uses CommonMark as the underlying markup language."><meta name="keywords" content="Pandoc, UTF, DITA, specializations, Markdown, CommonMark"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Markdown DITA syntax reference</title></head><body id="markdown-dita-syntax-reference"><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><a href="../topics/markdown-input.html">Markdown content</a></li><li><a href="../topics/lwdita-input.html">Lightweight DITA</a></li><li class="active"><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 DITA syntax reference</h1>
|
|
|
|
|
|
|
|
|
|
<div class="body"><p class="shortdesc">Markdown DITA uses
|
|
<a class="xref" href="http://commonmark.org" target="_blank" rel="external noopener">CommonMark</a> as the underlying markup language.</p>
|
|
<p class="p">Markdown DITA files must be UTF-8 encoded.</p>
|
|
<section class="section" id="markdown-dita-syntax-reference__titles-and-document-structure"><h2 class="title sectiontitle">Titles and document structure</h2>
|
|
|
|
<p class="p">Each header level will generate a topic and associated title:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Topic title
|
|
|
|
## Nested topic title</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><topic id="topic_title">
|
|
<title>Topic title</title>
|
|
<topic id="nested_topic_title">
|
|
<title>Nested topic title</title>
|
|
</topic>
|
|
</topic></code></pre>
|
|
<p class="p">Pandoc
|
|
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-header_attributes" target="_blank" rel="external noopener">header_attributes</a> can be used to define <code class="ph codeph">id</code> or
|
|
<code class="ph codeph">outputclass</code> attributes:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Topic title {#carrot .juice}</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><topic id="carrot" outputclass="juice">
|
|
<title>Topic title</title></code></pre>
|
|
<p class="p">If topic ID is not defined using header_attributes, the ID is generated from title contents.</p>
|
|
<p class="p">Pandoc
|
|
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-pandoc_title_block" target="_blank" rel="external noopener">pandoc_title_block</a>
|
|
extension can be used to group multiple level 1 headers under a common title:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>% Common title
|
|
|
|
# Topic title
|
|
|
|
# Second title</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><topic id="common_title">
|
|
<title>Common title</title>
|
|
<topic id="topic_title">
|
|
<title>Topic title</title>
|
|
</topic>
|
|
<topic id="second_title">
|
|
<title>Second title</title>
|
|
</topic>
|
|
</topic></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__topic-content"><h2 class="title sectiontitle">Topic content</h2>
|
|
|
|
<p class="p">In LwDITA compatible documents (MDITA) the first paragraph is treated as a <code class="ph codeph">shortdesc</code> element.
|
|
In generic Markdown documents all paragraphs appear inside the <code class="ph codeph">body</code> element.</p></section>
|
|
<section class="section" id="markdown-dita-syntax-reference__specialization-types"><h2 class="title sectiontitle">Specialization types</h2>
|
|
|
|
<p class="p">The following class values in
|
|
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-header_attributes" target="_blank" rel="external noopener">header_attributes</a> have a special meaning on level 1 headers:</p>
|
|
<ul class="ul">
|
|
<li class="li">
|
|
<code class="ph codeph">concept</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">task</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">reference</code></li>
|
|
</ul>
|
|
<p class="p">They can be used to change the Markdown DITA topic type to one of the built-in structural specialization
|
|
types.</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Task {.task}
|
|
|
|
Context
|
|
|
|
1. Command
|
|
|
|
Info.</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><task id="task">
|
|
<title>Task </title>
|
|
<taskbody>
|
|
<context>
|
|
<p>Context</p>
|
|
</context>
|
|
<steps>
|
|
<step>
|
|
<cmd>Command</cmd>
|
|
<info>
|
|
<p>Info.</p>
|
|
</info>
|
|
</step>
|
|
</steps>
|
|
</taskbody>
|
|
</task></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__sections"><h2 class="title sectiontitle">Sections</h2>
|
|
|
|
<p class="p">The following class values in
|
|
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-header_attributes" target="_blank" rel="external noopener">header_attributes</a> have a special meaning on header levels other than 1:</p>
|
|
<ul class="ul">
|
|
<li class="li">
|
|
<code class="ph codeph">section</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">example</code></li>
|
|
</ul>
|
|
<p class="p">They are used to generate
|
|
<a class="xref" href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/section.html" target="_blank" rel="external noopener"><code class="ph codeph">section</code></a> and
|
|
<a class="xref" href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/example.html" target="_blank" rel="external noopener"><code class="ph codeph">example</code></a> elements:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Topic title
|
|
|
|
## Section title {.section}
|
|
|
|
## Example title {.example}</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><topic id="topic_title">
|
|
<title>Topic title</title>
|
|
<body>
|
|
<section>
|
|
<title>Section title</title>
|
|
</section>
|
|
<example>
|
|
<title>Example title</title>
|
|
</example>
|
|
</body>
|
|
</topic></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__hard-line-breaks"><h2 class="title sectiontitle">Hard line breaks</h2>
|
|
|
|
<p class="p">A line break that is preceded by two or more spaces is parsed as a hard line break. Because DITA doesn't have a
|
|
<code class="ph codeph"><br></code> element for line break, hard line breaks are converted into
|
|
<code class="keyword markupname xmlpi"><?linebreak?></code> processing instructions.</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>foo··
|
|
baz</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><p>foo<?linebreak?>baz</p></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__links"><h2 class="title sectiontitle">Links</h2>
|
|
|
|
<p class="p">The format of local link targets is detected based on file extension. The following extensions are treated as
|
|
DITA files:</p>
|
|
<table class="table table-hover frame-none"><caption></caption><colgroup><col><col></colgroup><thead class="thead">
|
|
<tr class="row">
|
|
<th class="entry colsep-0 rowsep-1" id="markdown-dita-syntax-reference__links__entry__1">extension</th>
|
|
<th class="entry colsep-0 rowsep-1" id="markdown-dita-syntax-reference__links__entry__2">format</th>
|
|
</tr>
|
|
</thead><tbody class="tbody">
|
|
<tr class="row">
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.dita</code></td>
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">dita</code></td>
|
|
</tr>
|
|
<tr class="row">
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.xml</code></td>
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">dita</code></td>
|
|
</tr>
|
|
<tr class="row">
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.md</code></td>
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">markdown</code></td>
|
|
</tr>
|
|
<tr class="row">
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.markdown</code></td>
|
|
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">markdown</code></td>
|
|
</tr>
|
|
</tbody></table>
|
|
<p class="p">All other link targets use <code class="ph codeph">format</code> from file extension and are treated as non-DITA files.
|
|
Absolute links targets are treated as external scope links:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>[Markdown](test.md)
|
|
[DITA](test.dita)
|
|
[HTML](test.html)
|
|
[External](http://www.example.com/test.html)</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><xref href="test.md">Markdown</xref>
|
|
<xref href="test.dita">DITA</xref>
|
|
<xref href="test.html" format="html">HTML</xref>
|
|
<xref href="http://www.example.com/test.html" format="html" scope="external">External</xref></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__images"><h2 class="title sectiontitle">Images</h2>
|
|
|
|
|
|
<p class="p">Images used in inline content will result in inline placement. If a block level image contains a title, it will
|
|
be treated as an image wrapped in figure:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>An inline .
|
|
|
|
|
|
|
|
</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><p>An inline <image href="test.jpg"><alt>Alt</alt></image>.</p>
|
|
<image href="test.jpg" placement="break">
|
|
<alt>Alt</alt>
|
|
</image>
|
|
<fig>
|
|
<title>Title</title>
|
|
<image href="test.jpg">
|
|
<alt>Alt</alt>
|
|
</image>
|
|
</fig></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__key-references"><h2 class="title sectiontitle">Key references</h2>
|
|
|
|
<p class="p">Key reference can be used with
|
|
<a class="xref" href="http://spec.commonmark.org/0.18/#shortcut-reference-link" target="_blank" rel="external noopener">shortcut
|
|
reference links</a>:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>[key]
|
|
![image-key]</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><xref keyref="key"/>
|
|
<image keyref="image-key"/></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__inline"><h2 class="title sectiontitle">Inline</h2>
|
|
|
|
<p class="p">The following inline elements are supported:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>**bold**
|
|
*italic*
|
|
`code`
|
|
~~strikethrough~~</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><b>bold</b>
|
|
<i>italic</i>
|
|
<codeph>code</codeph>
|
|
<ph status="deleted">strikethrough</ph></code></pre>
|
|
</section>
|
|
<section class="section" id="markdown-dita-syntax-reference__lists"><h2 class="title sectiontitle">Lists</h2>
|
|
|
|
<p class="p">Unordered can be marked up with either hyphen or asterisk:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>* one
|
|
* two
|
|
- three
|
|
- four</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><ul>
|
|
<li>one</li>
|
|
<li>two
|
|
<ul>
|
|
<li>three</li>
|
|
<li>four</li>
|
|
</ul>
|
|
</li>
|
|
</ul></code></pre>
|
|
<p class="p">Ordered can be marked up with either number or number sign, followed by a period:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>1. one
|
|
2. two
|
|
#. three
|
|
#. four</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><ol>
|
|
<li>one</li>
|
|
<li>two
|
|
<ol>
|
|
<li>three</li>
|
|
<li>four</li>
|
|
</ul>
|
|
</li>
|
|
</ul></code></pre>
|
|
<p class="p">Definition lists use the
|
|
<a class="xref" href="http://michelf.com/projects/php-markdown/extra/#def-list" target="_blank" rel="external noopener">PHP
|
|
Markdown Extra</a> format:</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>Term
|
|
: Definition.</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><dl>
|
|
<delentry>
|
|
<dt>Term</dt>
|
|
<dd>Defintion.</dd>
|
|
</delentry>
|
|
</dl></code></pre>
|
|
<p class="p">Each definition entry must have only one term and contain only inline content.</p></section>
|
|
<section class="section" id="markdown-dita-syntax-reference__tables"><h2 class="title sectiontitle">Tables</h2>
|
|
|
|
|
|
<p class="p">Tables use
|
|
<a class="xref" href="http://fletcherpenney.net/multimarkdown/" target="_blank" rel="external noopener">MultiMarkdown</a> table
|
|
extension format:</p>
|
|
<pre class="pre codeblock normalize-space show-line-numbers show-whitespace"><code>| First Header | Second Header | Third Header |
|
|
| ------------ | :-----------: | -----------: |
|
|
| Content | *Long Cell* ||
|
|
| Content | **Cell** | Cell |</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><table>
|
|
<tgroup cols="3">
|
|
<colspec colname="col1"/>
|
|
<colspec colname="col2" align="center"/>
|
|
<colspec colname="col3" align="right"/>
|
|
<thead>
|
|
<row>
|
|
<entry>First Header </entry>
|
|
<entry>Second Header </entry>
|
|
<entry>Third Header </entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>Content </entry>
|
|
<entry namest="col2" nameend="col3"><i>Long Cell</i></entry>
|
|
</row>
|
|
<row>
|
|
<entry>Content </entry>
|
|
<entry><b>Cell</b></entry>
|
|
<entry>Cell </entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table></code></pre>
|
|
<p class="p">Table cells may only contain inline content and column spans; block content and row spans are not supported by
|
|
Markdown DITA.</p></section>
|
|
<section class="section" id="markdown-dita-syntax-reference__metadata"><h2 class="title sectiontitle">Metadata</h2>
|
|
|
|
|
|
|
|
|
|
<p class="p">
|
|
<a class="xref" href="http://www.yaml.org/" target="_blank" rel="external noopener">YAML</a> metadata block as defined in Pandoc
|
|
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-yaml_metadata_block" target="_blank" rel="external noopener">pandoc_metadata_block</a> can be used to specify different metadata elements. The supported elements
|
|
are:</p>
|
|
<ul class="ul">
|
|
<li class="li">
|
|
<code class="ph codeph">author</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">source</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">publisher</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">permissions</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">audience</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">category</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">keyword</code></li>
|
|
<li class="li">
|
|
<code class="ph codeph">resourceid</code></li>
|
|
</ul>
|
|
<p class="p">Unrecognized keys are output using <code class="ph codeph">data</code> element.</p>
|
|
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>---
|
|
author:
|
|
- Author One
|
|
- Author Two
|
|
source: Source
|
|
publisher: Publisher
|
|
permissions: Permissions
|
|
audience: Audience
|
|
category: Category
|
|
keyword:
|
|
- Keyword1
|
|
- Keyword2
|
|
resourceid:
|
|
- Resourceid1
|
|
- Resourceid2
|
|
workflow: review
|
|
---
|
|
|
|
# Sample with YAML header</code></pre>
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><title>Sample with YAML header</title>
|
|
<prolog>
|
|
<author>Author One</author>
|
|
<author>Author Two</author>
|
|
<source>Source</source>
|
|
<publisher>Publisher</publisher>
|
|
<permissions view="Permissions"/>
|
|
<metadata>
|
|
<audience audience="Audience"/>
|
|
<category>Category</category>
|
|
<keywords>
|
|
<keyword>Keyword1</keyword>
|
|
<keyword>Keyword2</keyword>
|
|
</keywords>
|
|
</metadata>
|
|
<resourceid appid="Resourceid1"/>
|
|
<resourceid appid="Resourceid2"/>
|
|
<data name="workflow" value="review"/>
|
|
</prolog></code></pre>
|
|
</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/markdown-input.html" title="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.">Markdown content</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></ul></div></nav></article></main></body></html> |