Nim-flavored Markdown и reStructuredText

Языки разметки Markdown (md) и reStructuredText (RST) предназначены для форматирования текстов с сложной структурой, форматированием и ссылками с помощью простого текстового представления.

Использование в командной строке

Использование (для преобразования Markdown в HTML):

nim md2html markdown_rst.md

Вывод:

You're reading it!

Команда md2tex вызывается аналогично md2html, но выводит файл .tex вместо .html.

Эти инструменты интегрированы в компилятор Nim; компилятор может выводить результат в HTML ^[1] или LaTeX ^[2].

Полный список поддерживаемых команд:

Основные теги

Если вы новичок в Markdown/RST, пожалуйста, ознакомьтесь со следующим:

1. Основные синтаксические конструкции Markdown
2. полное описание Markdown: Спецификация CommonMark
3. краткое введение в RST
4. справочник RST RST reference: полная шпаргалка по RST
5. более формальная 50-страничная спецификация RST.

Особенности

Большая часть функций реализована с некоторыми ограничениями и дополнительными особенностями, специфичными для Nim.

Поддерживаемые общие функции RST/Markdown:

• элементы тела
  • разделы
  • переходы
  • абзацы
  • маркированные списки с помощью +, *, -
  • нумерованные списки с использованием арабских цифр или букв: 1. ... 2. ... или a. ... b. ... или A. ... B. ...
  • сноски (включая вручную пронумерованные, автоматически пронумерованные, автоматически пронумерованные с меткой и автоматически пронумерованные с символом) и цитирования
  • списки полей
  • списки опций
  • цитаты
  • блоки строк
  • простые таблицы
  • директивы (см. официальную документацию в списке директив RST):
    • image, figure для включения изображений и видео
    • code
    • contents (таблица содержания), container, raw
    • include
    • примечания: "внимание", "осторожность", "опасность", "ошибка", "подсказка", "важно", "примечание", "совет", "предупреждение", "примечание"
    • определения подстановок: replace и image
  • комментарии
• встроенная разметка
  • курсив, жирный шрифт, inline literals, ссылки (включая встроенные URI), ссылки на подстановки, автономные ссылки, внутренние ссылки (встроенные и контурные)
  • `интерпретированный текст` с ролями :literal:, :strong:, emphasis, :sub:/:subscript:, :sup:/:superscript: (см. список ролей RST для описания).
  • внутренние целевые ссылки

Только RST-режим

• синтаксис RST для списков определений (т. е. дополнительный отступ после строки определения)
• отступы блоков кода, начинающиеся с ::

Особенности, специфичные для Markdown

• таблицы Markdown
• блоки кода Markdown. Для них можно указать те же дополнительные аргументы, что и для блоков кода RST (например, test или number-lines) но с однострочным синтаксисом, например:

  ```nim test number-lines=10
  echo "ok"
  ```

• ссылки Markdown [...](...)
• синтаксис Pandoc для автоматических ссылок [...], см. Ссылки для описания
• синтаксис Pandoc для сносок, включая [^10] (вручную пронумерованные) и [^someName] (автоматически пронумерованные с меткой)
• блоки кода Markdown с отступом в 4 или более пробелах
• заголовки Markdown
• блоки цитат Markdown
• синтаксис Markdown для списков определений
• использование 1 в качестве автонумератора в нумерованных списках, как в RST # (автонумератор 1 не может использоваться с # в одном списке)

Дополнительные особенности, специфичные для Nim

• ссылка на определения во внешних файлах, см. раздел Внешие ссылки
• директивы: code-block ^[3], title, index ^[3]
• предопределенные роли
  • :nim: (по умолчанию), :c: (язык программирования C), :python:, :yaml:, :java:, :cpp: (C++), :csharp (C#). То есть любой язык, который поддерживает highlite. Они включают соответствующее синтаксическое выделение в строчном коде.
    Примечание: роль по умолчанию для файлов Nim - :nim:, для *.rst - в настоящее время :literal:.
  • общие роли для выделения командной строки:
    • :cmd: для команд и синтаксиса общих оболочек
    • :console: то же самое для интерактивных сессий (команды должны предваряться $)
    • :program: для имён исполняемых файлов ^[3] (можно просто использовать :cmd: для одного слова)
    • :option: для параметров командной строки ^[3]
  • :tok:, роль для выделения токенов языка программирования
• курсив и полужирный (полужирный и курсив) с использованием ***
• :idx: роль для `интерпретированного текста`, чтобы включить ссылку на этот текст в индекс (пример: Nim index).
• двойной слеш // в списках опций служит префиксом для любой опции, которая начинается со слова (без каких-либо лидирующих символов, таких как -, --, /):

  //compile   compile the project
  //doc       generate documentation

  Здесь фиктивное значение // исчезнет, в то время как опции compile и doc останутся в конечном документе.

• смайлики/эмодзи

Ссылки

Для копирования и обмена ссылками Nim генерирует якоря для всех основных элементов документа:

• заголовки (включая заголовок документа)
• сноски
• явные якоря: внутренние перекрестные ссылки RST и встроенные внутренние цели
• символы Nim (внешние ссылки), см. Руководство по инструментам Nim DocGen для получения подробной информации.

Но непосредственное использование этих якорей имеет 2 проблемы:

1. якоря обычно искажаются (например, пробелы заменяются на тире и т. д.).
2. ручное использование якорей не проверяется, поэтому легко получить сломанные ссылки в проекте, если, например, изменилось написание заголовка или вы используете неверный относительный путь к документу.

Поэтому в реализации Nim есть синтаксис для использования исходных меток для ссылки. Такая ссылка может быть локальной/внутренней или внешней:

• Локальная ссылка (внутри данного файла) определяется стандартным RST или руководством пользователя Pandoc Markdown.
• Внешняя (между документами) ссылка — это функция, специфичная для Nim, хотя она не сильно отличается по синтаксису от локальной ссылки.

Разметка локальной ссылки

Для ссылки на объекты внутри любого данного файла, например, на заголовки, доступны 2 варианта синтаксиса:

Markdown                  RST

Some headline             Some headline
=============             =============

Ref. [Some headline]      Ref. `Some headline`_

Ссылка на разметку внешних источников

Синтаксис такой же, как для локальной ссылки, но якоря сохраняются в файлах .idx, поэтому их необходимо сгенерировать предварительно, и они должны быть загружены с помощью директивы .. importdoc::. Например, если мы хотим сослаться на раздел «Некоторое заголовок» в file1.md из file2.md, то file2.md может выглядеть так:

.. importdoc:: file1.md

Ref. [Some headline]

nim md2html --index:only file1.md  # creates ``htmldocs/file1.idx``
nim md2html file2.md               # creates ``htmldocs/file2.html``

Чтобы разрешить перекрестные ссылки между любыми файлами в любом порядке (особенно, если присутствуют циклические ссылки), настоятельно рекомендуется выполнить генерацию всех индексов:

nim md2html --index:only file1.md  # creates ``htmldocs/file1.idx``
nim md2html --index:only file2.md  # creates ``htmldocs/file2.idx``
nim md2html file1.md               # creates ``htmldocs/file1.html``
nim md2html file2.md               # creates ``htmldocs/file2.html``

и затем можно свободно ссылаться на любые объекты, как если бы эти 2 документа были фактически одним файлом.

Другое

Особенности

В настоящее время мы не стремимся к 100% совместимости с Markdown или RST в правилах распознавания разметки в строке, потому что это не принесёт значимой пользы пользователю. Этот парсер имеет 2 режима для разметки в строке:

1. Режим, похожий на Markdown, который включен опцией roPreferMarkdown (по умолчанию включен).
   Примечание: Функции RST, такие как директивы, всё ещё включены
2. Режим совместимости, который использует правила RST.

`\`   -- WRONG
``\`` -- GOOD
So single backticks can always be input: `\`` will turn to ` code

Ограничения

• нет поддержки Unicode в расчётах ширины символов
• элементы тела
  • нет римских цифр в нумерованных списках
  • нет блоков doctest
  • нет таблиц сетки
  • некоторые директивы отсутствуют (проверьте официальный список директив RST https://docutils.sourceforge.io/docs/ref/rst/directives.html): parsed-literal, sidebar, topic, math, rubric, epigraph, highlights, pull-quote, compound, table, csv-table, list-table, section-numbering, header, footer, meta, class
    • нет директив role и нет пользовательских интерпретируемых текстовых ролей
    • некоторые стандартные роли не поддерживаются (проверьте список ролей RST https://docutils.sourceforge.io/docs/ref/rst/roles.html)
    • нет поддержки общих предупреждений
• строчная разметка
  • нет simple-inline-markup
  • нет встроенных псевдонимов

Дополнительные ресурсы

• См. Руководство по инструментам Nim DocGen для получения подробной информации о команде nim doc и особенностях разметки документации в файлах .nim и проектах Nim.
• См. также документацию для модуля rst — парсера Nim RST/Markdown.