Математика в других элементах блока

Math также будет работать при вложении в другие блочные элементы, такие как списки или кавычки:

 - Список
- $$ а = 1 $$
> Блочная цитата
> $$ а = 1 $$
 

• Список А

• \[ а = 1 \]

Блочная цитата

\[ а = 1 \]

Прямая математика LaTeX

Хотите использовать amsmath LaTeX напрямую, без долларов? См. параметр расширенного синтаксиса.

Mathjax и математический анализ

При построении HTML с использованием расширения sphinx.ext.mathjax (включено по умолчанию) Если Dollarmath включен, Myst-Parser внедряет классы tex2jax_ignore (MathJax v2) и mathjax_ignore (MathJax v3) в раздел верхнего уровня каждого документа MyST и добавляет следующую конфигурацию MathJax по умолчанию:

MathJax версии 2 (см. препроцессор tex2jax:

 MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})
 

MathJax версии 3 (см. параметры документа):

 window.MathJax = {"options": {"processHtmlClass": "tex2jax_process|mathjax_process|math|output_area"}}
 

Это гарантирует, что MathJax обрабатывает только математику, идентифицированную расширениями Dollarmath и amsmath или указанную в математика директив.

Чтобы изменить это поведение, установите пользовательское регулярное выражение для определения обрабатываемых классов HTML, например myst_mathjax_classes="math|myclass" , или установите myst_update_mathjax=False , чтобы запретить это переопределение и обрабатывать все элементы HTML.

Линкифай

Добавление "linkify" к myst_enable_extensions (в файле конфигурации sphinx conf.py ) автоматически идентифицирует "голые" веб-URL и добавляет гиперссылки:

www. example.com -> www.example.com

Чтобы сопоставляться только URL-адресам, начинающимся со схемы, например http://example.com , установите myst_linkify_fuzzy_links=False .

Важно

Для этого расширения необходимо установить linkify-it-py. Либо напрямую; pip install linkify-it-py или через pip install myst-parser[linkify] .

Замены (с Jinja2)

Добавление "замена" to myst_enable_extensions (в файле конфигурации sphinx conf.py ) позволит вам добавлять замены, добавленные либо в conf.py , используя myst_substitutions :

 myst_substitutions = {
  "key1": "Я **замена**"
}
 

или вверху файла, во вступительной части (см. этот раздел):

 ---
мист:
  замены:
    key1: "Я **подмена**"
    ключ2: |
      ```{примечание}
      {{ключ1}}
      ```
    ключ3: |
      ```{изображение} img/fun-fish. png
      :alt: рыбный
      : ширина: 200 пикселей
      ```
    ключ4: пример
---
 

Important

Ключи во вступительной части имеют приоритет над ключами в conf.py .

Вы можете использовать эти замены как встроенные или как блоки, и вы даже можете вкладывать замены в другие замены (но циклические ссылки запрещены):

Ввод Markdown

 Встроенный: {{ key1 }}
Уровень блока:
{{ключ2}}
| столбец1 | столбец2 |
| -------- | -------- |
| {{key2}} | {{key3}} |
 

Визуализированный вывод

Встроенный: я замена

Уровень блока:

Примечание

Я замена

Важно

Замены будут оцениваться только там, где вы обычно используете Markdown, например. не в кодовых блоках:

 ```
{{ключ1}}
```
 

 {{ ключ1 }}
 

Следует также с осторожностью использовать неподходящие директивы для встроенных замен. Это может привести к неожиданным результатам.

оцениваются как выражения Jinja2, которые могут использовать фильтры, а также содержат среду Sphinx в контексте (как env ). Поэтому вы можете делать такие вещи, как:

 - версия: {{ env.config.version }}
- имя документа: {{ env.имя документа | верхний }}
- {{ "а" + "б" }}
 

При необходимости вы также можете изменить разделитель, например, установив в конф.py :

 myst_sub_delimiters = ["|", "|"]
 

Проанализирует: || "а" + "б" || . Однако это следует изменять с осторожностью, чтобы не повлиять на другие синтаксисы.

Точная логика обработки замен:

1. Объедините глобальные замены (указанные в conf.py ) с заменами вступительной части, чтобы создать переменный контекст (вступительная часть имеет приоритет)

2. Добавить сфинкса env в переменный контекст

3. Создайте строковое содержимое для рендеринга с помощью Jinja2 (передав ему переменный контекст)

4. Если замена является встроенной, а не директивой, рендеринг игнорирует синтаксис блоков (например, списки или блочные кавычки), в противном случае рендеринг выполняется со всеми правилами синтаксиса.

Замены и URL-адреса

Подстановки нельзя использовать напрямую в URL-адресах, например [ссылка](https://{{key4}}.com) или . Однако, поскольку замены Jinja2 позволяют использовать методы Python, вы можете использовать форматирование строк или замены:

 {{ '[ссылка](https://{}.com)'.format(key4) }}
{{ ''.replace('REPLACE', env.docname) }}
 

ссылка

https://myst-parser.readthedocs.io/en/latest/syntax/Optional.html

Заборы кода с использованием двоеточий

Путем добавления "colon_fence" к myst_enable_extensions (в конфигурационном файле sphinx conf.py ), вы также можете использовать разделители ::: для обозначения барьеров кода вместо ``` .

Преимущество использования двоеточий вместо обратных галочек заключается в том, что содержимое отображается правильно, когда вы работаете в любом стандартном редакторе Markdown. Он идеально подходит для директив типа предупреждения (как описано в Директивах) или таблиц с заголовками, например:

Ввод уценки

 ::: {примечание}
Этот текст является **стандартным** _Markdown_
:::
:::{table} Это **стандартный** заголовок _Markdown_
:выравнивание: по центру
:ширина: сетка
азбука | мнп | xyz
--- | --- | ---
123 | 456 | 789:::
 

Примечание

Этот текст является стандартным Markdown

Подобно обычным директивам, эти директивы также могут быть вложенными:

 ::::{важно}
:::{примечание}
Этот текст является **стандартным** _Markdown_
:::
::::
 

Важно

Примечание

Этот текст является стандартным Уценка

, а также можно использовать опции параметров:

 :::{предостережение} Это *также* **Markdown**
:класс: предупреждение
Этот текст является **стандартным** _Markdown_
:::
 

Этот также Уценка

Этот текст стандартный Уценка

Предупреждающие директивы

Изменено в версии 0. 13.0: myst_admonition_enable устарело и заменено myst_enable_extensions = ["colon_fence"] (см. выше). Кроме того, классы теперь должны быть установлены с опцией :class: myclass .

См. также Предостережения в формате HTML.

Списки определений

Путем добавления "deflist" в myst_enable_extensions (в файле конфигурации sphinx conf.py ), вы сможете использовать списки определений. Списки определений используют плагин markdown-it-py deflist, который сам основан на спецификации списка определений Pandoc.

Этот синтаксис может быть полезен, например, как альтернатива вложенным маркированным спискам:

• Срок 1

  • Определение

• Срок 2

  • Определение

Использование вместо:

 Термин 1
: Определение
Срок 2
: Определение
 

Термин 1

Определение

Термин 2

Определение

Из документации Pandoc:

Каждый термин должен помещаться на одной строке, за которой может следовать пустая строка, а также одно или несколько определений. Определение начинается с двоеточия или тильды, которые могут иметь отступ в один или два пробела.

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

Вот более сложный пример, демонстрирующий некоторые из этих возможностей:

Термин с уценкой

Определение со ссылкой

Второй абзац

Второе определение

Термин 2

Определение 2a

Определение 2b

Термин 3

 Кодовый блок
 

Котировка

Окончательное определение, которое может включать даже изображения:

Это было создано из:

 Термин *с уценкой*
: Определение [со ссылкой] (синтаксис/списки определений)
  Второй абзац
: второе определение
Срок 2
  ~ Определение 2а
  ~ Определение 2б
Срок 3
: блок кода
: > Цитата
: Окончательное определение, которое может даже включать изображения:
   png" alt="fishy">
 

Списки задач

Добавив "список задач" в myst_enable_extensions (в файле конфигурации sphinx conf.py ), вы сможете использовать списки задач. Списки задач используют плагин списков задач markdown-it-py, и применяются к элементам списка уценки, начинающимся с [ ] или [x] :

 - [ ] Предмет, который нужно сделать
- [x] Готовый предмет
 

• Предмет, который нужно сделать

• Готовое изделие

Списки полей

Новое в версии 0.16.0.

Списки полей — это сопоставления имен полей с телами полей, на основе синтаксиса reStructureText.

 :только имя:
: имя: тело
:*Вложенный синтаксис*: И имя, и тело сообщения могут содержать **вложенный синтаксис**.
:Paragraphs: Так как маркер поля может быть достаточно длинным, второй
   и последующие строки абзаца не должны совпадать
   с первой строкой.
:Выравнивание 1: Если тело поля начинается с первой строки. ..
              Затем все тело поля должно иметь одинаковый отступ.
:Выравнивание 2:
  Если тело поля начинается на следующей строке...
  Тогда отступ всегда два пробела.
:блоки:
  Помимо абзацев, в теле поля может использоваться любой синтаксис блока:
  - Мне
  - Сам
  - я
  ```питон
  print("Привет, мир!")
  ```
 

только имя:

имя:

корпус

Вложенный синтаксис :

И имя, и тело могут содержать вложенный синтаксис .

Абзацы:

Поскольку маркер поля может быть довольно длинным, второй и последующие строки абзаца не должны совпадать с первой строкой.

Выравнивание 1:

Если тело поля начинается с первой строки…

Тогда все тело поля должно иметь одинаковый отступ.

Выравнивание 2:

Если тело поля начинается на следующей строке…

Тогда отступ всегда два пробела.

блоков:

Помимо абзацев, в теле поля может использоваться любой синтаксис блока:

• Я

• Сам

• я

 print("Привет, мир!")
 

Известный случай использования списков полей для использования в строках документации API, как это используется в средствах визуализации строк документации Sphinx:

 ```{py:function} send_message(отправитель, приоритет)
Отправить сообщение получателю
:param str sender: человек, отправляющий сообщение
:param priority: Приоритет сообщения, может быть от 1 до 5. 
:тип приоритет: int
:return: идентификатор сообщения
:rtype: интервал
:поднимает ValueError: если message_body превышает 160 символов
```
 

send_message( отправитель , приоритет )

Отправить сообщение получателю

Параметры:

• отправитель ( стр ) – Лицо, отправляющее сообщение

• priority ( int ) — Приоритет сообщения, может быть числом 1-5

Возвращает:

идентификатор сообщения

Тип возврата:

целое число

Поднимает:

ValueError – если message_body превышает 160 символов

Примечание

В настоящее время sphinx.ext.autodoc не поддерживает MyST, см. Использование sphinx.ext.autodoc в файлах Markdown.

Встроенные атрибуты

Новое в версии 0. 19: эта функция есть в бета-версии и может измениться в будущих версиях. Он заменяет предыдущее расширение attrs_image , которое теперь устарело.

Путем добавления "attrs_inline" в myst_enable_extensions (в файле конфигурации sphinx conf.py ), вы можете включить синтаксический анализ встроенных атрибутов после определенных встроенных синтаксисов. Это адаптировано из встроенных атрибутов djot, а также связанные с пролетами в квадратных скобках pandoc.

Атрибуты указываются в фигурных скобках после встроенного синтаксиса. Внутри фигурных скобок распознается следующий синтаксис:

• .foo указывает foo как класс. Таким образом можно дать несколько классов; они будут объединены.

• #foo указывает foo в качестве идентификатора. Элемент может иметь только один идентификатор; если задано несколько идентификаторов, используется последний.

• key="value" или key=value определяет атрибут "ключ-значение". Кавычки не нужны, когда значение полностью состоит из Буквенно-цифровые символы ASCII или _ или : или - . Обратная косая черта может использоваться внутри значений в кавычках. Примечание поддерживаются только определенные клавиши, см. ниже.

• % начинается комментарий, который заканчивается следующим % или концом атрибута ( } ).

Например, следующая уценка:

 - [Отрывок текста с атрибутами]{#spanid .bg-warning},
  {ref}`ссылка на диапазон `
- `Литерал с атрибутами`{#literalid .bg-warning},
  {ref}`ссылка на литерал 
- Автоссылка с атрибутами: {.bg-warning title="a title"}
- [Ссылка с атрибутами](синтаксис/атрибуты){#linkid .bg-warning},
  {ref}`ссылка на ссылку `
- ![Изображение с атрибутом](img/fun-fish. png){#imgid .bg-warning w=100px align=center}
  {ref}`ссылка на изображение `
 

будет проанализировано как:

• Фрагмент текста с атрибутами, ссылка на пролет

• Литерал с атрибутами , ссылка на литерал

• Автоссылка с атрибутами: https://example.com

• Ссылка с атрибутами, ссылка на ссылку

• ссылка на изображение

атрибуты "ключ-значение"

идентификатор и class поддерживаются для всех встроенных синтаксисов, но для каждого синтаксиса поддерживаются только определенные атрибуты ключ-значение.

Для литералов поддерживаются следующие атрибуты:

Для изображений поддерживаются следующие атрибуты (эквивалентно директиве image ):

• ширина / w определяет ширину изображения (в % , px , em , см и т. д.)

• height / h определяет высоту изображения (в px , em , см и т.д.)

• align / a определяет масштаб изображения ( слева , по центру или справа )

HTML-изображения

MyST предоставляет несколько различных вариантов синтаксиса для включения изображений в вашу документацию, как описано ниже.

Первый — это стандартный синтаксис Markdown:

 ![рыбный](img/fun-fish.png)
 

Это правильно скопирует изображение в папку сборки и отобразит его во всех выходных форматах (HTML, TeX и т. д.). Однако он ограничен в конфигурации, которую можно применить, например, в настройке ширины.

Как обсуждалось выше, MyST позволяет использовать директивы, такие как изображение и рисунок (см. документацию sphinx):

 ```{изображение} img/fun-fish. png
:alt: рыбный
:класс: бг-первичный
: ширина: 200 пикселей
:выравнивание: по центру
```
 

Теперь можно установить дополнительные параметры, однако, в отличие от синтаксиса Markdown, этот синтаксис не будет отображать изображение в обычных средствах просмотра Markdown (например, при просмотре файлов на GitHub).

Последний вариант — прямое использование HTML, который также анализируется MyST. Обычно это плохой вариант, потому что HTML обрабатывается как необработанный текст во время процесса сборки, поэтому sphinx не распознает, что файл изображения должен быть скопирован, и не будет выводить HTML в выходных форматах, отличных от HTML.

Парсинг HTML вам в помощь!

Путем добавления "html_image" к myst_enable_extensions (в файле конфигурации sphinx conf.py ), MySt-Parser попытается преобразовать любые изолированные теги img (т. е. не завернутые в какой-либо другой HTML) во внутреннее представление, используемое в sphinx.

Допустимые атрибуты эквивалентны image директива: src, alt, class, width, height и name. Любые другие атрибуты будут удалены.

HTML-изображение также можно использовать в качестве встроенного!

Я встроенное изображение:

Цифры уценки

Путем добавления "colon_fence" в myst_enable_extensions (в файле конфигурации sphinx conf.py ), мы можем комбинировать два вышеуказанных расширенных синтаксиса, для создания полностью совместимой с Markdown версии директивы фигура с именем цифра-md .

Изменено в версии 0.13.0: myst_figure_enable с директивой figure устарела и заменена на myst_enable_extensions = ["colon_fence"] и figure-md .

Блок рисунка должен содержать только два компонента; изображение в синтаксисе Markdown или HTML и один абзац для заголовка.

Заголовок является необязательным и используется в качестве эталона рисунка:

 :::{figure-md} рис-цель
:класс: мой класс

Это подпись в **Markdown**
:::
 

Это подпись на Markdown

Как мы видим здесь, на установленную нами цель можно сослаться:

 [Иди к рыбе!](фиг-мишень)
 

Иди к рыбе!

Предостережения HTML

Путем добавления "html_admonition" в myst_enable_extensions (в sphinx conf.py Файл конфигурации), вы можете включить синтаксический анализ

 

Это **название**
Это *контент*

 

 <дел>
Абзац 1
Абзац 2

 <дел>
Некоторый **контент**
  <дел>
  
*название*
  
Абзац 1
  
Абзац 2