> 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/podrobnye-stati/30-how-to-write-in-markdown-on-overleaf.md).
# Как писать в Markdown в Overleaf
**Обновление после публикации** (добавлено 13 мая 2017 г.): Мы благодарны Виту Новотному, автору/сопровождающему `markdown` пакета, за письмо с полезными замечаниями относительно исходной статьи. Мы рады опубликовать эту обновлённую версию, в которой учтены и включены его советы и предложения.
### Хм, что?
[Markdown](https://kirkstrobeck.github.io/whatismarkdown.com/) — это лёгкий язык разметки (поняли? 😉), который позволяет писать что-то обычным текстом с помощью *очень* простых правил, а затем преобразовывать это в форматированные результаты, например HTML. Он очень популярен среди разработчиков программного обеспечения и программистов именно благодаря своей простоте (и, добавлю, отлично подходит и для заметок!).
Например, чтобы написать быстрый список покупок:
```
# Список покупок
*Не забудьте* захватить как можно больше во время предстоящих [распродаж](http://acme-marg.com)!
## Еда
- запечённая фасоль
- спагетти
## Канцелярия
- блокнот
- карандаши
```
И вы получите в качестве HTML-вывода, используя такой инструмент, как [pandoc](http://pandoc.org/):
```html
Список покупок
Не забудьте захватить как можно больше во время предстоящих распродаж!
Еда
- запечённая фасоль
- спагетти
Канцелярия
```
Красиво и просто! Вы можете найти другие синтаксические конструкции для Markdown [здесь](https://daringfireball.net/projects/markdown/syntax).
### И что это значит для меня?
Многие пользователи LaTeX довольны своими прекрасно набранными в LaTeX документами, но не могут не испытывать укол зависти к пользователям Markdown — потому что, ну, разметка LaTeX *можно* иногда становится довольно многословной. Да, списки, мы смотрим на *вас*...
Хорошая новость в том, что замечательный новый [`markdown` пакет LaTeX](https://ctan.org/pkg/markdown) позволяет писать синтаксис markdown в ваших документах LaTeX (то есть более простой ввод) и всё равно получать красиво набранные PDF! Всё, что вам нужно, — это загрузить `markdown` пакет в ваш документ и заключить ваш Markdown-материал в `markdown` среду:
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
# Список покупок
*Не забудьте* захватить как можно больше во время предстоящих [распродаж](http://acme-marg.com)!
## Еда
- запечённая фасоль
- спагетти
## Канцелярия
- блокнот
- карандаши
\end{markdown}
\end{document}
```
Или если вы предпочитаете поместить ваш Markdown-материал в `*.md` файл:
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\markdownInput{example.md}
\end{document}
```
Отлично! Скорее всего, это очень порадует разработчиков, потому что теперь они могут просто копировать свою `.md` документацию!
### Могу ли я всё ещё использовать команды LaTeX, если пишу Markdown?
Да, вы всё ещё можете использовать команды LaTeX в своём Markdown-материале! Просто передайте `гибридную` параметр `markdown`:
```latex
\usepackage[hybrid]{markdown}
...
- блокнот для письма (такой, на обложке которого большими буквами $E=mc^2$)
```
### Как я могу использовать буквальные символы, такие как '#' и '\_' (подчёркивания)?
#### Ввод символа '#'
Вы не можете ввести символ '#' *внутри `markdown` окружения*. Не поможет даже `\#` Нужно определить команду вроде `\newcommand{\texthash}{\#}`, а затем использовать `\texthash` в вашем `markdown` окружения. Аналогично для подчёркиваний, особенно когда их больше одного в одной строке, например `$y = m_1 + n_2$`. Иногда проще завершить текущее `markdown` окружение и писать проблемные строки в обычном режиме LaTeX, а затем начать другое `markdown` окружение.
#### Ввод '\_' (подчёркивания) и '\`' (обратной кавычки)
**Обновление** (добавлено 13 мая 2017 г.): Начиная с `markdown` версии 2.5 вы можете установить `underscores = false` и `codeSpans = false` чтобы отключить подчёркивания и обратные кавычки. Это позволяет писать нижние индексы в математике и кавычки в гибридном режиме без экранирования. У нас есть звёздочки для выделения, так что единственное, что действительно теряется, — это примеры встроенного кода. Спасибо Виту за подсказку!
#### Окружения, которых следует избегать...
И хотя вы можете использовать обратные кавычки для записи встроенного текста как есть или сделать отступ в четыре пробела для блока текста как есть, не используйте `lstlisting` и `minted` окружения LaTeX внутри `markdown` окружений. Просто не делайте этого.
#### Использование HTML в окружении markdown
И нет, вы не можете использовать HTML внутри окружения LaTeX `markdown` (хотя в обычном Markdown так делать часто). Извините.
**Обновление** (добавлено 13 мая 2017 г.): Начиная с `markdown` v2.3 есть `html` параметр, который не будет выводить HTML-теги как есть, если они присутствуют в вашем Markdown-материале, хотя содержимое тегов он тоже не будет на самом деле форматировать — то есть `Привет!` будет просто отображаться как Привет! обычным шрифтом. Но HTML-сущности, такие как `©` будут отображаться как ©. Спасибо Виту за то, что он указал на это.
### Рекомендуемые параметры пакета markdown
Один набор `markdown` параметров пакета, которые могут оказаться полезными:
```latex
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses,hybrid]{markdown}
```
Эти параметры позволяют использовать
* синтаксис Markdown для сносок (например, `[^1]`);
* списки определений и `#` для нумерованных списков;
* «настоящие» многоточия (…).
Вот [полный пример](https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm) в галерее Overleaf, а вот [другой пример](https://www.overleaf.com/articles/how-to-write-using-rich-text-format-and-markdown-in-latex-and-overleaf/dbqrxvftzskw).
### Гиперссылки и сноски: как?
В примере Overleaf гиперссылка является сноской. Как сделать её гиперссылкой hyperref?
`markdown` настраивается, так что вы можете определить, как именно вы хотите отображать разные элементы. Если добавить это в преамбулу, получится именно так:
```latex
\markdownSetup{renderers={
link = {\href{#2}{#1}}
}}
```
**Обновление** (добавлено 13 мая 2017 г.): `rendererPrototypes` использовался в начальной версии. Обычным пользователям рекомендуется использовать `renderers` для собственных определений, поскольку `rendererPrototypes` предназначен для авторов пакетов, чтобы они могли задавать значения по умолчанию. Если вы измените `rendererPrototypes`, вы рискуете, что другой пакет переопределит ваши настройки. Спасибо Виту за то, что он указал на это!
### Добавление изображений (обновлено 8 ноября 2022 г.)
* **Примечание**: Следующий пример использует графический файл (`example-image.pdf`), предоставленный `пакетом mwe` . Эти графические файлы распространяются TeX Live и, следовательно, хранятся на серверах Overleaf, что делает их доступными в качестве заполнителей изображений, как в примере ниже.
Изображения можно включать в markdown, используя разметку следующего формата:
```latex
```
Надеюсь, имена параметров `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}
\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` подключает другие пакеты, включая [`keyval`](https://ctan.org/pkg/keyval?lang=en) и [`graphicx`](https://ctan.org/pkg/graphicx?lang=en), чтобы использовать предоставляемые ими команды и возможности. Здесь ширина изображения задаётся с помощью `\setkeys` команды, предоставляемой `keyvals`. `Gin` — это "семейство" ключей, определённое `graphicx` пакет.
* **Примечание**: Поскольку используется команда LaTeX, здесь `\setkeys`, *внутри* окружения `markdown` , требуется `гибридную` опция пакета markdown.
#### Изменение идентификаторов размещения плавающих объектов (более продвинутый вариант)
Синтаксис markdown для включения рисунков не позволяет напрямую указывать идентификаторы размещения плавающих объектов, но их можно изменить, переопределив способ отображения рисунка:
```latex
\markdownSetup{renderers={
image = {\begin{figure}[hbt!]
\centering
\includegraphics{#3}%
\ifx\empty#4\empty\else
\caption{#4}%
\fi
\end{figure}}
}}
```
Дополнительную информацию см. в [документации markdown](https://mirror.apps.cam.ac.uk/pub/tex-archive/macros/generic/markdown/markdown.html).
### Можно ли создавать таблицы с помощью markdown в LaTeX? 😀
К сожалению, нет. Таблицы поддерживаются только в [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) , а пакет LaTeX `markdown` пока не поддерживает это.
**Обновление** (добавлено 13 мая 2017 г.): По совету Вита можно использовать `contentBlocks` расширение синтаксиса начиная с версии 2.4 или подправить `рендерер inputFencedCode` , чтобы быстро преобразовать некоторый текст в стиле CSV в таблицу.
### Ещё больше полезностей пакета markdown...?
Как уже упоминалось ранее, это классный способ для заметок, а в сочетании с некоторыми хорошими классами документов LaTeX или настройками пакетов он позволяет вам получить красивый конспект прямо по итогам лекции. Например, вы можете использовать его с [классами Tufte](https://www.overleaf.com/gallery/tagged/tufte):
```latex
\documentclass{tufte-handout}
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses, hybrid]{markdown}
\begin{document}
\markdownInput{PHY303-lecture-12Nov2016.md}
\end{document}
```
А короткий и простой синтаксис, делающий написание списков гораздо удобнее, означает, что теперь у нас есть *действительно быстрый* способ писать [презентации Beamer](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw) и [постеры](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw)!
Удачи!
---
# 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/podrobnye-stati/30-how-to-write-in-markdown-on-overleaf.md?ask=&goal=
```
`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.