Quarto. Язык markdown

2025-03-23 · 5 мин. для прочтения

Quarto. Язык markdown.

Содержание

1 Общая информация

Quarto основан на Pandoc и использует его вариацию markdown в качестве базового синтаксиса документа.
Pandoc markdown — это расширенная и слегка переработанная версия синтаксиса Markdown Джона Грубера.

2 Форматирование текста

Markdown:

*курсив*, **полужирный**, ***полужирный курсив***

курсив , полужирный , полужирный курсив

Markdown:
```
верхний индекс^2^ нижний индекс~2~
```
- верхний индекс² / нижний индекс₂
Markdown:
```
~~зачеркивание~~
```
- ~~зачеркивание~~
Markdown:
```
`verbatim code`
```
- verbatim code

3 Заголовки

Markdown:

# Заголовок 1

## Заголовок 2

### Заголовок 3

#### Заголовок 4

##### Заголовок 5

###### Заголовок 6

4 Ссылки и изображения

Markdown:

<https://quarto.org>

[Quarto](https://quarto.org)

![Caption](elephant.png)

[![Caption](elephant.png)](https://quarto.org)

[![Caption](elephant.png "An elephant")](https://quarto.org)

[![](elephant.png){fig-alt="Alt text"}](https://quarto.org)

5 Списки

Списки в Quarto требуют целой пустой строки над списком.
В противном случае список не будет отображаться в виде списка, а будет отображаться как обычный текст вдоль одной строки.

Markdown:

* unordered list
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1

Вывод:
- unordered list
  - sub-item 1
  - sub-item 2
    - sub-sub-item 1

Markdown:

*   item 2

    Continued (indent 4 spaces)

Вывод:
- item 2
  Continued (indent 4 spaces)

Markdown:

1. ordered list
2. item 2
    i) sub-item 1
         A.  sub-sub-item 1

Вывод:
1. ordered list
2. item 2
  1. sub-item 1
    1. sub-sub-item 1
Markdown:
```
- [ ] Task 1
- [x] Task 2
```
Вывод:
- Task 1
- Task 2

6 Сноски

Pandoc поддерживает нумерацию и форматирование сносок:

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

Можно писать сноски в виде отдельных абзацев:

Here is an inline note.^[Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.]

Идентификаторы сносок должны быть уникальными в пределах документа.
В книгах Quarto главы объединяются в один документ для определённых форматов (включая PDF, DOCX и EPUB), поэтому идентификаторы сносок должны быть уникальными для всех глав.

7 Таблицы

Markdown:

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Вывод:
Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

8 Исходный код

Следует использовать ``` для разграничения блоков исходного кода:
```
```
code
```
```
Можно указать язык для подсветки синтаксиса блоков кода:
```
```python
1 + 1
```
```
Если ваш язык не поддерживается, вы можете использовать язык default, чтобы получить оформление по умолчанию:
```
```default
code
```
```
Эквивалентом краткой формы является длинная форма, которая использует язык как класс (например, .python ) внутри фигурных скобок:
```
```{.python}
1 + 1
```
```
Длинная форма позволяет добавлять атрибуты к блоку:
```
```{.python filename="run.py"}
code
```
```

9 Аннотации кода

Аннотации ячеек кода включают в себя:
- Завершение каждой аннотированной строки комментарием и номером аннотации в угловых скобках (например, # <2> ). Используйте одно и то же число, чтобы охватить аннотацию на нескольких строках.
- Добавление упорядоченного списка сразу после ячейки кода, где каждый элемент соответствует номеру аннотации в коде.
```
```r
x <- 1:10  # <1>
y <- x^2   # <2>
z <- x^3   # <2>
```
1. Create a vector `x`, and then,
2. compute `y` and `z`
```
Возможные позиции аннотаций для вывода HTML:
- below (по умолчанию): По умолчанию аннотации отображаются под ячейкой кода.
- hover : Аннотации отображаются при наведении мыши на маркер строки.
- select : Аннотации появляются при нажатии на маркер и могут быть удалены повторным нажатием.
Чтобы изменить положение аннотации по умолчанию, используйте поле метаданных code-annotations в заголовке документа:
```
---
code-annotations: hover
---
```

10 Необработанный контент

Необработанный контент может быть включён напрямую без разбора Quarto, используя атрибут raw:
```
```{=html}
<iframe src="https://quarto.org/" width="500" height="400"></iframe>
```
```
Для вывода PDF используйте необработанный блок LaTeX:
```
```{=latex}
\renewcommand*{\labelitemi}{\textgreater}
```
```
Можно включить необработанный контент в строку:
```
Here's some raw inline HTML: `<a>html</a>`{=html}
```

11 Уравнения

Используйте разделители $ для строчной математики и разделители $$ выделенной математики.
Markdown:
```
inline math: $E = mc^{2}$
```
Вывод: inline math: $E = mc^{2}$
Markdown:
```
display math:

$$E = mc^{2}$$
```
Вывод: display math:

\[E = mc^{2}\]

Если вы хотите определить пользовательские макросы TeX, включите их в разделители $$, заключенные в блок .hidden:
```
::: {.hidden}
$$
 \def\RR{{\bf R}}
 \def\bold#1{{\bf #1}}
$$
:::
```

Для MathJax (применяется по умолчанию) можно использовать команды \def, \newcommand, \renewcommand, \newenvironment, \renewenvironment, \let.

12 Диаграммы

Quarto имеет встроенную поддержку для встраивания диаграммы Mermaid и Graphviz:

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

13 Разрывы страниц

Шорткод pagebreak позволяет вставлять в документ собственный разрыв страницы (например, в LaTeX это будет \newpage, в MS Word — собственный разрыв страницы docx, в HTML — директива CSS page-break-after: always).
Собственные разрывы страниц поддерживаются для HTML, LaTeX, Context, MS Word, Open Document, ePub (для других форматов используется символ перевода страницы).
```
page 1

{{< pagebreak >}}

page 2
```

14 Порядок атрибутов

div и span в pandoc могут иметь любую комбинацию идентификаторов, классов и атрибутов ключ-значение.
Чтобы pandoc распознал их, они должны быть предоставлены в определённом порядке: идентификаторы, классы, а затем атрибуты ключ-значение.
Любой из них может быть опущен, но должен следовать этому порядку, если они предоставлены.
Например, следующее является допустимым:
```
[This is good]{#id .class key1="val1" key2="val2"}
```
Следующее pandoc не распознает:
```
[This does *not* work!]{.class key="val" #id}
```

15 Сочетания клавиш

Шорткод kbd можно использовать для описания сочетаний клавиш в документации. В форматах Javascript он попытается определить операционную систему формата и отобразит правильное сочетание клавиш. В форматах печати он выведет информацию о сочетаниях клавиш для всех операционных систем.
```
To print, press {{< kbd Shift-Ctrl-P >}}.
To open an existing new project, press {{< kbd mac=Shift-Command-O win=Shift-Control-O linux=Shift-Ctrl-L >}}.
```

Обновлено 2025-03-29

Markdown Science-Writing

Authors

Дмитрий Сергеевич Кулябов

Профессор кафедры теории вероятностей и кибербезопасности

Мои научные интересы включают физику, администрирование Unix и сетей.

← Блок-схема 2025-03-24

Quarto. Перекрёстные ссылки 2025-03-23 →