topics/markdown-input.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->

<topic id="markdown-input">
  <title>Markdown content</title>
  <shortdesc>
    <xref keyref="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.</shortdesc>
  <prolog>
    <metadata>
      <keywords>
        <indexterm><xmlatt>format</xmlatt></indexterm>
        <indexterm>authoring formats<indexterm>Markdown</indexterm></indexterm>
        <indexterm>Markdown</indexterm>
        <indexterm>CommonMark</indexterm>
      </keywords>
    </metadata>
  </prolog>
  <body>
    <p>In the words of its creators:</p>

    <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.”</lq>

    <p>DITA Open Toolkit now allows you to use Markdown files directly in topic references and export DITA content as
      Markdown.</p>

    <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>
      <title>Adding Markdown topics</title>
      <p>To add a Markdown topic to a DITA publication, create a topic reference in your map and set the
          <xmlatt>format</xmlatt> attribute to <codeph>markdown</codeph> so the toolkit will recognize the source file
        as Markdown and convert it to DITA:</p>
      <p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;?xml version="1.0" encoding="utf-8"?>
&lt;!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
&lt;map>
  &lt;topicref href="markdown-dita-topic.md" <b>format="markdown"</b>/>
&lt;/map></codeblock></p>
      <p>The <codeph>markdown</codeph> format uses a relatively lenient document parsing approach to support a wide
        range of content and Markdown syntax constructs. </p>
      <note>The Markdown support is based on
        <xref keyref="commonmark"/>, a strongly defined, highly compatible specification of Markdown.</note>
    </section>
  </body>
</topic>