# Пишите на Markdown

Черновик на привычном Markdown — и на выходе PDF или редактируемый документ для соавторов.

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

## Создайте отчёт

1. Выберите **Новый проект → Использовать шаблон → Пустой документ Markdown**.
2. Назовите проект **Полевые заметки** и откройте `main.md`.
3. Вставьте этот пример, затем выберите **Скомпилировать заново** или нажмите **⌘Enter / Ctrl+Enter**.
4. Если Oleafly предложит настроить нужный движок, завершите настройку и скомпилируйте ещё раз.

```markdown title="main.md"
---
title: "Field notes"
author: "Alex Chen"
date: ""
---

# Question

Does the revised procedure reduce measurement time?

## Method

1. Prepare the sample.
2. Repeat the measurement three times.
3. Record the elapsed time.

## Observations

| Run | Time (s) | Note |
| --- | --- | --- |
| 1 | 12 | First pass |
| 2 | 10 | Repeated pass |

The **mean time** will be compared with the baseline.
```

В PDF должны быть название, заголовки, нумерованный список и таблица. Метаданные между первой парой строк `---` задают название документа и автора.

## Типы документов

Добавьте строку `type` во front matter, чтобы собрать документ как отчёт, книгу, слайды, постер, письмо или резюме. Без `type` или со значением, которое Oleafly не знает, документ собирается как статья.

| `type` | Что собирается | Подставляется, если вы не задали сами |
| --- | --- | --- |
| `article` | Статья | Ничего |
| `report` или `thesis` | Отчёт, в котором каждый заголовок `#` начинает главу | `documentclass: report` |
| `book` | Книга, в которой каждый заголовок `#` начинает главу | `documentclass: book` |
| `slides` | Слайды Beamer 16:9. Заголовок `#` начинает раздел, а заголовок `##` начинает слайд | `aspectratio: 169` |
| `poster` | Одностраничный постер Beamer с заголовком из `title`, `subtitle`, `author` и `institute` | Бумага A0, книжная ориентация |
| `letter` | Письмо с вашим адресом и адресом получателя, темой, обращением и заключительной фразой | `documentclass: scrlttr2` |
| `cv` | Компактная статья | `geometry: margin=2cm` и `pagestyle: empty` |

Ваш собственный front matter главнее. Значение, которое вы задали сами, например `documentclass`, `aspectratio` или `geometry`, заменяет то, которое подставляет тип.

Для слайдов задайте `slide-level`, чтобы выбрать уровень заголовка, с которого начинается слайд. При `slide-level: 1` слайд начинает каждый заголовок `#`. Слайды собираются как обычный PDF, поэтому их может показать **Начать показ** на панели инструментов предпросмотра. См. [Показ слайдов](/docs/present-slides/).

Постер имеет размер A0, если вы не зададите `papersize` равным `a1`, `a2`, `a3` или `a4`. Другие размеры, например `letter` или `a5`, игнорируются. Добавьте `orientation: landscape`, чтобы получить широкий постер.

Письмо берёт адрес получателя из `to`, а ваш из `from`. `opening` — это приветствие, а `closing` — строка перед вашим именем, которое берётся из `author`. `subject` становится темой письма, а при отсутствии `subject` — `title`. Пишите адрес списком, по одной строке на элемент.

```markdown title="main.md"
---
type: letter
author: "Alex Chen"
from:
  - "Department of Physics"
  - "1 University Road"
to:
  - "Dr. Sam Lee"
  - "Editorial Office"
subject: "Revised manuscript"
opening: "Dear Dr. Lee,"
closing: "Yours sincerely,"
---

Thank you for the reviewers' comments. The revised manuscript answers each one.
```

**Тип документа** в [настройках документа](/docs/document-settings/#markdown) записывает строку `type` за вас. [Экспорт в LaTeX](/docs/export/#what-each-format-keeps) тоже следует типу, а [экспорт в PowerPoint](/docs/export/#presentation-and-book-exports) слайдов использует тот же `slide-level`. [`oleafly build`](/docs/cli/#build-a-project) собирает каждый тип так же, как приложение.

## Редактирование исходника и визуальное редактирование

У переключателя в начале панели инструментов три режима. **Код** редактирует Markdown напрямую. **Визуально** даёт форматированное редактирование заголовков, абзацев, списков, ссылок, изображений и таблиц. **Оба** показывает исходник и форматированный текст вместе. Откройте его меню, чтобы выбрать **Друг под другом** или **Разделить**. Новые проекты открываются в режиме «Код», и каждый проект запоминает режим, в котором вы его оставили.

Подчёркивание, выделение цветом, верхний и нижний индексы — это инструменты форматирования Pandoc в режиме «Код». Их кнопки скрыты в режиме «Визуально». Используйте «Код» для работы с метаданными, синтаксисом цитирования и другими конструкциями исходника.

[Скачать исходник примера](/examples/writing-example.md)

## Каждый инструмент панели инструментов

Выделяйте текст перед щелчком по инструменту форматирования. В режиме «Код» большинство инструментов обёртывает выделение или вставляет заполнитель. Откройте **Другие параметры форматирования** (`…`), чтобы добраться до элементов, не поместившихся в панель.

### Код / Визуально

Переключайтесь между режимами **Код**, **Визуально** и **Оба**. В любом режиме документ остаётся исходником Markdown.

### Отменить

Отменяет последнее изменение. ⌘Z / Ctrl+Z.

### Повторить

Возвращает отменённое изменение. **⌘Shift+Z / Ctrl+Shift+Z**.

### Заголовок → Название

Выберите **Название** в меню заголовков, чтобы вставить `# Title`. Замените текст заголовка на собственный.

### Заголовок → Раздел

Выберите **Раздел** в меню заголовков, чтобы вставить `## Section`. Замените текст заголовка на собственный.

### Заголовок → Подраздел

Выберите **Подраздел** в меню заголовков, чтобы вставить `### Subsection`. Замените текст заголовка на собственный.

### Заголовок → Подподраздел

Выберите **Подподраздел** в меню заголовков, чтобы вставить `#### Subsubsection`. Замените текст заголовка на собственный.

### Заголовок → Мелкий заголовок

Выберите **Мелкий заголовок** в меню заголовков, чтобы вставить `##### Minor heading`. Замените текст заголовка на собственный.

### Заголовок → Заголовок абзаца

Выберите **Заголовок абзаца** в меню заголовков, чтобы вставить `###### Paragraph heading`. Замените текст заголовка на собственный.

### Маркированный список

Начинает неупорядоченный список. `- Item`.

### Нумерованный список

Начинает последовательность. `1. Item`.

### Список задач

В режиме «Код» добавьте задачу и замените `[ ]` на `[x]`, когда она выполнена. `- [ ] Task`.

### Цитата блоком

Помещает цитату на отдельной строке. `> quoted text`.

### Полужирный

Выделяет выделенный текст. `**text**`; ⌘B / Ctrl+B.

### Курсив

Выделяет термин курсивом. `*text*`; ⌘I / Ctrl+I.

### Зачёркнутый

Помечает текст как устаревший. `~~text~~`.

### Код в строке

Форматирует имя файла, команду или идентификатор. Текст в обратных кавычках.

### Подчёркнутый

Выделите фразу в режиме «Код». `[text]{.underline}`.

### Выделение цветом

Выделите фразу в режиме «Код». `[text]{.mark}`.

### Верхний индекс

Выделите степень в режиме «Код». `^text^`.

### Нижний индекс

Выделите нижний индекс в режиме «Код». `~text~`.

Подчёркивание и выделение цветом используют атрибуты Pandoc, поэтому форматирование попадает в PDF. Используйте эти инструменты вместо добавления «сырых» HTML-тегов в рукопись.

### Вставить ссылку

В режиме **Код**: вставляет `[link text](url)`. Замените оба заполнителя.

В режиме **Визуально**: открывает **Адрес URL ссылки**. Введите адрес и примените его к выделенному фрагменту. Используйте **Убрать ссылку**, чтобы сохранить текст без ссылки.

### Вставить изображение

В режиме **Код**: вставляет `![caption](image-filename)`. Замените путь и подпись.

В режиме **Визуально**: открывает **Файл изображения**. Введите путь внутри проекта, например `figures/plot.png`, и примените его.

Изображения PNG, JPG, PDF, SVG, GIF, WebP и BMP попадают в PDF. SVG, GIF и WebP Oleafly преобразует за вас при компиляции. Изображения TIFF, AVIF, HEIC и JPEG XL вставить нельзя: компиляция останавливается и называет файл, поэтому сохраните его в одном из других форматов и скомпилируйте снова. Если преобразование не удалось, проверьте, что изображение открывается, или сохраните его как PNG или PDF.

### Вставить таблицу

В режиме **Код**: вставляет три столбца, заголовок и две строки данных. Замените названия столбцов и ячейки.

В режиме **Визуально**: вставляет редактируемую таблицу тех же начальных размеров.

### Нарисовать диаграмму

Открывает [конструктор диаграмм](/docs/figures-diagrams/) в режиме Mermaid. Нарисуйте блок-схему на холсте или отредактируйте код Mermaid, затем выберите **Вставить как Mermaid**, чтобы добавить её в позицию курсора как ограждённый блок кода `mermaid`. См. [Диаграммы Mermaid](#mermaid-diagrams).

### Сведения о документе

Показывает заголовки, рисунки, таблицы, формулы, метки, цитирования и задачи документа в порядке исходника, каждое со ссылкой на свою строку. Он также читает название, авторов, ключевые слова, дату и аннотацию из front matter и может скопировать их для формы подачи. См. [Сведения о документе](/docs/document-insights/).

### Настройки документа

Меняет тип документа, класс документа, размер страницы, число колонок, поля, основной шрифт, размер шрифта, язык, межстрочный интервал и нумерацию разделов. Oleafly записывает ваш выбор во front matter в YAML, который читает Pandoc, и добавляет блок front matter, если его не было. См. [Настройки документа](/docs/document-settings/#markdown).

### Сведения о проекте

В режиме **Код**: показывает статистику проекта и сведения о выделенном фрагменте.

В режиме **Визуально**: показывает статистику поверхности визуального редактирования.

### Найти

В режиме **Код**: открывает поиск в активном файле сочетанием ⌘F / Ctrl+F.

В режиме **Визуально**: кнопка «Найти» на панели исходника скрыта.

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

![Лабораторный журнал в Markdown, отредактированный в виде исходника и в визуальном виде, при этом таблица и список задач остаются согласованными.](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## Формулы и блоки кода

Вводите строчную математику как `$x^2$`. Выключную формулу заключите между двумя парами знаков доллара:

```markdown
$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$
```

Для примера кода заключите код в тройные обратные кавычки и укажите язык после открывающего ограждения. Это конструкции исходника; на панели инструментов Markdown нет отдельной кнопки для формул или ограждённых блоков кода.

В режиме «Визуально» ограждённый блок остаётся блоком кода и сохраняет свой язык и пустые строки, поэтому диаграммы Mermaid не теряются. Введите тройные обратные кавычки, чтобы начать новый блок, и нажмите Tab, чтобы сделать отступ внутри него.

## Диаграммы Mermaid

Выберите **Нарисовать диаграмму** на панели инструментов, чтобы создать блок-схему Mermaid в конструкторе диаграмм. **Вставить как Mermaid** добавляет её как ограждённый блок кода:

````markdown
```mermaid
flowchart LR
  A[Sample] --> B[Measure]
```
````

В режиме **Оба** форматированная сторона рисует блок как диаграмму. PDF требует изображения, поэтому конструктор дополнительно сохраняет готовый PNG по пути `figures/mermaid-<hash>.png`, и компиляция ставит это изображение на место блока. Поэтому диаграмма появляется и в скомпилированном PDF, и в экспорте в Word, HTML, EPUB и PowerPoint. Если потом отредактировать блок вручную, в PDF будет показываться код, пока вы снова не вставите диаграмму из конструктора или не сохраните её. См. [Mermaid в документах Markdown](/docs/figures-diagrams/#mermaid-in-markdown-documents).

## Текст на других языках

Oleafly подбирает шрифты для письменностей, которые находит в документе, поэтому корейский, японский, китайский, арабский, иврит, греческий, кириллица, деванагари, тайский и ещё несколько письменностей отображаются без всякой настройки. Символы и эмодзи тоже получают шрифт, причём эмодзи чёрно-белые. Документ, написанный в основном на арабском или иврите, идёт справа налево.

Китайские иероглифы встречаются и в китайском, и в японском тексте, поэтому задайте `lang` в front matter, чтобы получить нужный шрифт: `ja` для японского, `zh` для упрощённого китайского, `zh-TW` для традиционного китайского или `ko` для корейского. Без `lang` Oleafly ориентируется на текст: кана означает японский, а хангыль — корейский.

```markdown title="main.md"
---
title: "実験ノート"
lang: ja
---
```

Шрифты, которые вы выбираете сами, имеют приоритет. Когда front matter задаёт `mainfont` или `CJKmainfont` либо `header-includes` настраивает шрифты, Oleafly эту часть не трогает.

### Символы, отсутствующие в PDF

Когда ни в одном используемом шрифте нет символа, PDF всё равно собирается без него, а компиляция показывает предупреждение с примером отсутствующих символов. Чтобы это исправить:

- Для корейского, китайского или японского текста задайте в front matter `CJKmainfont` со шрифтом, установленным на вашем компьютере, в котором есть эти символы.
- Для другого текста так же задайте `mainfont`. **Шрифт текста** в [Настройках документа](/docs/document-settings/#markdown) запишет его за вас.
- Для редкого символа используйте изображение.

## Цитирование и библиография

Импортируйте или создайте `references.bib`, добавьте `bibliography: references.bib` в метаданные YAML и ссылайтесь на существующий ключ с помощью `[@citation-key]`. Pandoc использует библиографию, чтобы создать форматированные цитирования и список литературы.

Если front matter не называет библиографию или называет файл, которого нет, компиляция использует файлы `.bib` проекта, содержащие цитируемые вами ключи. Цитата без какой-либо библиографии остаётся в PDF в том виде, как вы её набрали, например `[@smith2020]`, поэтому можно сначала писать, а ссылки добавить позже. Документ, который ничего не цитирует, собирается без чтения файлов `.bib`.

[Найти источники и управлять ими →](/docs/citations/)

## Импорт и экспорт

Чтобы сохранить существующий черновик в Markdown, создайте пустой документ Markdown, вставьте черновик в `main.md` и импортируйте его изображения и библиографию. Отдельный импорт **Документ Markdown** в библиотеке сейчас преобразует черновик в LaTeX. В разделе [Маршруты импорта](/docs/import-project/) объясняются оба пути.

Скомпилируйте документ в PDF или используйте **Экспорт**, чтобы создать Word, HTML, Typst, LaTeX, PowerPoint, EPUB или обычный текст. Экспорты в LaTeX и Typst сохраняют библиографию и ссылаются на ваши файлы изображений, а не копируют их, поэтому держите эти файлы рядом с экспортом. Когда Pandoc что-то пропускает, экспорт сохраняется с предупреждениями, а **Показать предупреждения** перечисляет, что было отброшено. Чтобы поделиться исходным Markdown и его ресурсами, используйте ZIP с исходником. В разделе [Экспорт работы](/docs/export/) описана последовательность действий и проверки, которые стоит выполнить в преобразованном файле.
