Markdown files

Markdown is a popular plain-text file format for creating formatted text. For example, many software developers use it for easily creating documentation. It has many different variants (also called flavors). supports the most widely-used flavor, CommonMark, and shows a preview of how the file looks when converted into HTML.

The CommonMark syntax has very complicated rules about how to write some elements - so that conversion to HTML works as clearly as possible. This topic doesn't go into all the details. To learn more, read the latest version of the CommonMark specification.

  1. Start importing a Markdown file.

  2. In the Document import options window, select the MD file, and click Change filter and configuration.

  3. The Document import settings window appears. From the Filter drop-down list, choose Markdown filter.

    srt-filter-OPTIONS

Choose how to handle formatting

Markdown uses special characters like asterisks (*) and underscores (_) for formatting text. The basic rule is: a pair of single asterisks or underscores means italic (same as the <em> HTML tag), and a pair of double asterisks or underscores means bold (same as the <strong> HTML tag).

Choose how to handle line breaks

Soft line breaks (when the line ends with a newline character):

Hard line breaks (when the line ends with two spaces or a <br> HTML tag):

Choose how to handle code blocks

There are two kinds of code blocks in Markdown:

always imports indented code blocks. Settings in the Code blocks define what happens to fenced code blocks.

Even if you don't import fenced code blocks for translation, they will be visible in the preview.

Choose how to handle HTML content

Markdown files can have HTML content inside. When the HTML content is in blocks of neighboring lines, you can import them as separate embedded files under the Markdown file. To do this, at the bottom of the Document import options window, select the Import embedded objects checkbox.

imports these embedded files using its HTML filter, which is, at the time of writing (Q2 2024) not configurable, and does not import HTML comments.

HTML comments in Markdown look like this
  • first line begins with the characters <!--

  • last line contains the characters -->.

Examples:

<!-- This

is a

comment -->

 

<!-- This is another comment -->

When a comment is not inside a HTML block (that is, it is between lines of non-HTML content), you can import it into the Markdown file itself. To do this, in the Markdown filter configuration's HTML section, select the Import top-level HTML comments as translatable checkbox.

In the current version, can't import HTML comments inside HTML blocks.