> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/ru/baza-znanii/166-writing-markdown-in-latex-documents.md).

# Написание Markdown в документах LaTeX

## Введение

Чтобы использовать markdown в документе LaTeX, вам нужно подключить [`markdown` пакет](https://www.ctan.org/pkg/markdown) в преамбуле вашего документа:

```latex
\usepackage[settings]{markdown}
```

где `[settings]` является *необязательным* набором параметров, используемых для настройки или включения определённых возможностей пакета. См. `markdown` пакет [документацию](https://anorien.csc.warwick.ac.uk/mirrors/CTAN/macros/generic/markdown/markdown.html) для [описания параметров пакета (опций)](https://anorien.csc.warwick.ac.uk/mirrors/CTAN/macros/generic/markdown/markdown.html#options).

В этой статье мы кратко рассмотрим как *встроенный* markdown — написанный внутри вашего документа — так и импортирование *внешнего* markdown, содержащегося в текстовом файле.

* **Примечание**: В общем случае использование markdown внутри документа LaTeX следует рассматривать как дополнительный и удобный вариант для оформления некоторых элементов содержимого документа, а не как альтернативный синтаксис, полностью заменяющий сам LaTeX.

## Использование внешних файлов markdown

Используйте команду

```latex
\markdownInput{filename}
```

чтобы включить файл markdown `filename`.

Следующий пример вставляет файл с именем `example.md`. Используйте ссылку под листингами кода, чтобы открыть их как проект Overleaf:

**`main.tex`**

```latex
\documentclass{article}
\title{Использование пакета markdown}
\usepackage[smartEllipses]{markdown}
\begin{document}

\markdownInput{example.md}

\end{document}
```

**`example.md`**

```latex
%% example.md

# Я файл markdown.

И я могу делать *выделение*.
## С подзаголовками

> Блочные цитаты
> записываются так.
>
> Они могут занимать несколько абзацев,
> если хотите.

Используйте 3 дефиса для длинного тире. Используйте 2 дефиса для
диапазонов (например, "это всё в главах 12--14").
Три точки ... будут преобразованы в многоточие
(при условии, что вы включите опцию smartEllipses
в преамбуле). Поддерживается Unicode.
```

[Откройте эти файлы как проект Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name\[]=main.tex\&snip\[]=%5Cdocumentclass%7Barticle%7D%0A%5Ctitle%7BUsing+the+markdown+package%7D%0A%5Cusepackage%5BsmartEllipses%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5CmarkdownInput%7Bexample.md%7D%0A%0A%5Cend%7Bdocument%7D\&snip_name\[]=example.md\&snip\[]=%25%25+example.md%0A%0A%23+I%27m+a+markdown+file.%0A%0AAnd+I+can+do+%2Aemphasis%2A.%0A%23%23+With+sub-headers%0A%0A%3E+Block+quotes+are%0A%3E+written+like+so.%0A%3E%0A%3E+They+can+span+multiple+paragraphs%2C%0A%3E+if+you+like.%0A%0AUse+3+dashes+for+an+em-dash.+Use+2+dashes+for+%0Aranges+%28ex.%2C+%22it%27s+all+in+chapters+12--14%22%29.+%0AThree+dots+...+will+be+converted+to+an+ellipsis+%0A%28provided+you+include+the+smartEllipses+option+%0Ain+your+preamble%29.+Unicode+is+supported.\&main_document=main.tex)

Этот пример выдаёт следующий результат:

![Изображение, показывающее результат работы пакета markdown](/files/a38f9931e0733691061cb52feb96f18603f2595d)

## Использование встроенного markdown

Используйте `markdown` окружение:

```latex
\begin{markdown}
...ваш markdown
помещается сюда...
\end{markdown}
```

для написания встроенного markdown, как показано в следующем примере:

```latex
\documentclass{article}
\usepackage[hashEnumerators,smartEllipses]{markdown}
\begin{document}

Использование встроенного markdown:

\begin{markdown}
Заголовок h1
============

Абзацы разделяются пустой строкой.

2-й абзац. *Курсив*, **жирный** и `моноширинный`. Маркированные списки
выглядят так:

* этот
* тот
* другой

> Блочные цитаты
> записываются так.
>
> Они могут занимать несколько абзацев,
> если хотите.

Заголовок h2
------------

Вот нумерованный список (используйте опцию `hashEnumerators`, если хотите использовать решётки):

#. первый пункт
#. второй пункт
#. третий пункт

\end{markdown}
\end{document}
```

[Откройте этот пример в Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5BhashEnumerators%2CsmartEllipses%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%0AUsing+inline+markdown%3A%0A%0A%5Cbegin%7Bmarkdown%7D%0AAn+h1+header%0A%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%0A%0AParagraphs+are+separated+by+a+blank+line.+%0A%0A2nd+paragraph.+%2AItalic%2A%2C+%2A%2Abold%2A%2A%2C+and+%60monospace%60.+Itemized+lists%0Alook+like%3A%0A%0A%2A+this+one%0A%2A+that+one%0A%2A+the+other+one%0A%0A%3E+Block+quotes+are%0A%3E+written+like+so.%0A%3E%0A%3E+They+can+span+multiple+paragraphs%2C%0A%3E+if+you+like.%0A%0AAn+h2+header%0A------------%0A%0AHere%27s+a+numbered+list+%28use+%60hashEnumerators%60+option+if+you+want+to+use+hashes%29%3A%0A%0A%23.+first+item%0A%23.+second+item%0A%23.+third+item%0A%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

Этот пример выдаёт следующий результат:

![Пример верстки встроенного markdown в Overleaf](/files/07310e7844c985b45211bcbca8ddcea262fd6e03)

## Возможности и параметры пакета markdown

Здесь мы рассмотрим несколько [возможностей и параметров](https://anorien.csc.warwick.ac.uk/mirrors/CTAN/macros/generic/markdown/markdown.html) , предоставляемых `markdown` пакетом.

### Включение кода в markdown

Есть два способа отображения фрагментов кода (блоков кода) внутри markdown:

* сделав отступ у каждой строки блока минимум на четыре пробела или один таб, или
* используя так называемые [ограниченные блоки кода](#using-fenced-code-blocks)

#### Использование отступов для отображения блоков кода

Следующий пример использует 4 или более пробелов в начале каждой строки кода — некоторые строки используют 6, 8 или 10 пробелов в зависимости от требуемой величины отступа:

```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
Вот несколько фрагментов кода, с отступом минимум в 4 пробела.
\vspace{6mm}

\begin{markdown}

Вот фрагмент C:

    /* Позвольте мне выполнить итерацию ... */

    int i;
    for(i=0; i<10; i++)
    {
      do-something(i)
    }

Вот немного HTML:

    <html>
      <head>
        <title>Заголовок страницы</title>
      </head>
      <body>
        <h1>Это заголовок</h1>
          <p>Это абзац.</p>
      </body>
    </html>

\end{markdown}
\end{document}
```

[Откройте этот пример в Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown+code+snippets\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0AHere+are+some+code+fragments+indented+by+at+least+4+space+characters.%0A%5Cvspace%7B6mm%7D%0A%0A%5Cbegin%7Bmarkdown%7D%0A%0AHere+is+a+fragment+of+C%3A%0A%0A++++%2F%2A+Let+me+iterate+...+%2A%2F%0A%0A++++int+i%3B%0A++++for%28i%3D0%3B+i%3C10%3B+i%2B%2B%29%0A++++%7B%0A++++++do-something%28i%29%0A++++%7D%0A%0AHere+is+some+HTML%3A%0A%0A++++%3Chtml%3E%0A++++++%3Chead%3E%0A++++++++%3Ctitle%3EPage+Title%3C%2Ftitle%3E%0A++++++%3C%2Fhead%3E%0A++++++%3Cbody%3E%0A++++++++%3Ch1%3EThis+is+a+Heading%3C%2Fh1%3E%0A++++++++++%3Cp%3EThis+is+a+paragraph.%3C%2Fp%3E%0A++++++%3C%2Fbody%3E%0A++++%3C%2Fhtml%3E%0A%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

Этот пример выдаёт следующий результат:

![Пример верстки кода через markdown](/files/dcadbf13faac207ac929071c5487429218315a64)

#### Использование ограниченных блоков кода

Ограниченный блок кода создаётся, если написать либо

* три обратные кавычки (` ``` `), или
* три тильды (`~~~`)

в строках до и после блока кода. При использовании этого метода вам не нужно делать отступы у строк, но вам нужно использовать опцию `fencedCode` в преамбуле:

```latex
\usepackage[fencedCode]{markdown}
```

Вот пример создания ограниченных блоков кода с помощью 3 обратных кавычек (` ``` `):

````latex
\documentclass{article}
\usepackage[fencedCode]{markdown}
\begin{document}
\begin{markdown}

```
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
```

```
    <html>
      <head>
        <title>Заголовок страницы</title>
      </head>
      <body>
        <h1>Это заголовок</h1>
          <p>Это абзац.</p>
      </body>
    </html>
```
\end{markdown}
\end{document}
````

[Откройте этот пример в Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown+fenced+code+blocks\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5BfencedCode%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0A%0A%60%60%60%0Aif+%28a+%3E+3%29+%7B%0A++++moveShip%285+%2A+gravity%2C+DOWN%29%3B%0A%7D%0A%60%60%60%0A%0A%60%60%60%0A++++%3Chtml%3E%0A++++++%3Chead%3E%0A++++++++%3Ctitle%3EPage+Title%3C%2Ftitle%3E%0A++++++%3C%2Fhead%3E%0A++++++%3Cbody%3E%0A++++++++%3Ch1%3EThis+is+a+Heading%3C%2Fh1%3E%0A++++++++++%3Cp%3EThis+is+a+paragraph.%3C%2Fp%3E%0A++++++%3C%2Fbody%3E%0A++++%3C%2Fhtml%3E%0A%60%60%60%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

Этот пример выдаёт следующий результат:

![Использование ограниченных блоков кода с пакетом markdown для LaTeX](/files/abe263502e6f9565bf831baaf662990ce53d78b8)

#### Подсветка синтаксиса

Ограниченные блоки кода поддерживают подсветку синтаксиса: имя языка пишется после первого набора обратных кавычек (`` ` ``). Например, следующий блок определяется как Javascript, если первый набор обратных кавычек записан как ` ``` js `:

````latex
``` js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
```
````

Для LaTeX пакет `minted` можно использовать для подсветки синтаксиса, как показано в следующем примере, содержащем немного Javascript (` ``` js `) и HTML (` ``` html `):

````latex
\documentclass{article}
\usepackage{minted}
\usepackage[fencedCode]{markdown}
\begin{document}
\begin{markdown}

``` js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
```

``` html
    <html>
      <head>
        <title>Заголовок страницы</title>
      </head>
      <body>
        <h1>Это заголовок</h1>
          <p>Это абзац.</p>
      </body>
    </html>
```
\end{markdown}
\end{document}
````

[Откройте этот пример в Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+markdown+fenced+code+blocks\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bminted%7D%0A%5Cusepackage%5BfencedCode%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0A%0A%60%60%60+js%0Aif+%28a+%3E+3%29+%7B%0A++++moveShip%285+%2A+gravity%2C+DOWN%29%3B%0A%7D%0A%60%60%60%0A%0A%60%60%60+html%0A++++%3Chtml%3E%0A++++++%3Chead%3E%0A++++++++%3Ctitle%3EPage+Title%3C%2Ftitle%3E%0A++++++%3C%2Fhead%3E%0A++++++%3Cbody%3E%0A++++++++%3Ch1%3EThis+is+a+Heading%3C%2Fh1%3E%0A++++++++++%3Cp%3EThis+is+a+paragraph.%3C%2Fp%3E%0A++++++%3C%2Fbody%3E%0A++++%3C%2Fhtml%3E%0A%60%60%60%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

Этот пример выдаёт следующий результат:

![Подсветка синтаксиса с minted и markdown](/files/eae8c0d33e8b9a81981b572d4811449a7359cbd3)

### Списки

Предыдущие примеры [демонстрируют создание неупорядоченных списков](#using-inline-markdown) в markdown с использованием `*` символа. Упорядоченные списки можно создавать, используя `#` символ, если `hashEnumerators` опция была указана:

```latex
\usepackage[hashEnumerators]{markdown}
```

Также можно создавать вложенные списки, как показано в следующем примере:

```latex
\documentclass{article}
\usepackage[hashEnumerators]{markdown}
\begin{document}
\begin{markdown}
Вот нумерованный список, который содержит вложенный список:

#. Сначала возьмите эти ингредиенты:

      * морковь
      * сельдерей
      * чечевица

#. Сварите немного воды.

#. Сложите всё в кастрюлю и следуйте этому алгоритму:

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

    Не заденьте деревянную ложку, иначе она упадёт.
\end{markdown}
\end{document}
```

[Откройте этот пример в Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Creating+a+nested+list+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5BhashEnumerators%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AHere+is+a+numbered+list+that+contains+a+nested+list%3A%0A%0A%23.+First%2C+get+these+ingredients%3A%0A%0A++++++%2A+carrots%0A++++++%2A+celery%0A++++++%2A+lentils%0A%0A%23.+Boil+some+water.%0A%0A%23.+Dump+everything+in+the+pot+and+follow+this+algorithm%3A%0A%0A++++++++find+wooden+spoon%0A++++++++uncover+pot%0A++++++++stir%0A++++++++cover+pot%0A++++++++balance+wooden+spoon+precariously+on+pot+handle%0A++++++++wait+10+minutes%0A++++++++goto+first+step+%28or+shut+off+burner+when+done%29%0A%0A++++Do+not+bump+wooden+spoon+or+it+will+fall.%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

Этот пример выдаёт следующий результат:

![Создание нумерованных списков с помощью пакета markdown для LaTeX](/files/d4e4eb1e99dd6191ea6836c5d2b56e5d1551d018)

### Включение LaTeX внутри markdown

Если вы включите `гибридную` опцию, вы сможете смешивать код LaTeX в Markdown!

```latex
\documentclass{article}
\usepackage[hybrid]{markdown}
\begin{document}

\begin{markdown}
Встроенные математические формулы можно создавать так: $\omega = d\phi / dt$.
Формулу в отдельном блоке можно записать так:

\begin{equation}
I = \int \rho R^{2} dV
\end{equation}

\end{markdown}
\end{document}
```

[Откройте этот пример в Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+LaTeX+code+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5Cbegin%7Bmarkdown%7D%0AInline+math+equations+can+be+created+like+this%3A+%24%5Comega+%3D+d%5Cphi+%2F+dt%24.+%0ADisplay+math+can+be+written+as%3A%0A%0A%5Cbegin%7Bequation%7D%0AI+%3D+%5Cint+%5Crho+R%5E%7B2%7D+dV%0A%5Cend%7Bequation%7D%0A%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

Этот пример выдаёт следующий результат:

![Использование кода LaTeX в markdown](/files/cc7c9d2fb6725346d71d59f0073e4a8a62743724)

### Включение изображений

* **Примечание**: Следующий пример использует графический файл (`example-image.pdf`), предоставленный `пакетом mwe` . Эти графические файлы распространяются TeX Live и, следовательно, хранятся на серверах Overleaf, что делает их доступными в качестве заполнителей изображений, как в примере ниже.

Изображения можно включать в markdown, используя разметку следующего формата:

```latex
![alt-text](file-name "подпись к изображению")
```

Надеюсь, имена параметров `alt-text`, `file-name` и `"подпись к изображению"` объясняют, что они делают. Вот пример, демонстрирующий это:

```latex
\documentclass{article}
\usepackage[hybrid]{markdown}
% Пакет mwe предоставляет примерные изображения. Его подключение
% не обязательно, потому что эти изображения находятся в пути поиска LaTeX.
% Здесь мы подключаем его для наглядности в этом примере.
\usepackage{mwe}
\begin{document}
\begin{markdown}
Этот пример показывает, как импортировать графический файл. Здесь мы используем
пример изображения, предоставленный пакетом `mwe`.

% Используйте \setkeys{Gin}, если вам нужно изменить размер отображения изображения

\setkeys{Gin}{width=.5\linewidth}
![Это alt-текст для описания моего изображения.](example-image.jpg "Пример изображения, предоставленный пакетом \texttt{mwe}.")
\end{markdown}
\end{document}
```

[Откройте этот пример в Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+images+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%25+The+mwe+package+provides+example+images.+Loading+it+is%0A%25+not+essential+because+those+images+are+in+LaTeX%27s+search+path.+%0A%25+Here%2C+we+load+it+for+clarity+in+this+example.%0A%5Cusepackage%7Bmwe%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AThis+example+shows+how+to+import+a+graphics+file.+Here+we+are+using+an%0Aexample+image+provided+by+the+%60mwe%60+package.%0A%0A%25+Use+%5Csetkeys%7BGin%7D+if+you+need+to+change+an+image%27s+display+size%0A%0A%5Csetkeys%7BGin%7D%7Bwidth%3D.5%5Clinewidth%7D%0A%21%5BThis+is+alt+text+to+describe+my+image.%5D%28example-image.jpg+%22An+example+image+provided+by+the+%5Ctexttt%7Bmwe%7D+package.%22%29%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)

Этот пример выдаёт следующий результат:

![Показано, как импортировать изображения в markdown](/files/9382e922c0559066f87a57f4a520891f8275edf0)

#### Примечание о ширине изображения

Как и большинство пакетов, `markdown` подключает другие пакеты, включая [`keyval`](https://ctan.org/pkg/keyval?lang=en) и [`graphicx`](https://ctan.org/pkg/graphicx?lang=en), чтобы использовать предоставляемые ими команды и возможности. Здесь ширина изображения задаётся с помощью `\setkeys` команды, предоставляемой `keyvals`. `Gin` — это "семейство" ключей, определённое `graphicx` пакетом.

* **Примечание**: Поскольку используется команда LaTeX, здесь `\setkeys`, *внутри* окружения `markdown` , требуется `гибридную` опция пакета markdown.

## Дополнительная литература

Overleaf опубликовал и другие статьи об использовании markdown:

* [Как писать в Markdown в Overleaf](/latex/ru/podrobnye-stati/30-how-to-write-in-markdown-on-overleaf.md)
* [Markdown в LaTeX со стилем](/latex/ru/podrobnye-stati/32-markdown-into-latex-with-style.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/latex/ru/baza-znanii/166-writing-markdown-in-latex-documents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.