Конвертер markdown в документу docx установленного образца. Поддерживает все возможности GitHub Flavored Markdown.
Таблицы
Таблицы могут быть сформированы двумя способами:
- Markdown — простой и естественный способ. Следует спецификации GFM.
- HTML — более сложный, однако позволяет объединять ячейки и менять положение текста в ячейке
Markdown
Написании таблиц в markdown само по себе простое. Можно воспользоваться сайтом создания таблиц или писать самостоятельно. Также можно использовать стартовый шаблон, такой как ниже.
| | | |
|---|---|---|
| | | |
| | | |
Если заполнить его данными, выйдет примерно такая таблица:
| Имя | Возраст | Город |
|-----------|---------|-----------------|
| Алексей | 28 | Москва |
| Иван | 22 | Казань |
| Мария | 34 | Санкт-Петербург |
Аналог в HTML:
<table>
<thead>
<tr>
<th>Имя</th>
<th>Возраст</th>
<th>Город</th>
</tr>
</thead>
<tbody>
<tr>
<td>Алексей</td>
<td>28</td>
<td>Москва</td>
</tr>
<tr>
<td>Иван</td>
<td>22</td>
<td>Казань</td>
</tr>
<tr>
<td>Мария</td>
<td>34</td>
<td>Санкт-Петербург</td>
</tr>
</tbody>
</table>
В Markdown первая строчка всегда выравнена по центру, последующие — по ширине
HTML
Выше представлен пример реализации аналогичной таблицы как в markdown, так и в HTML. В отличии от markdown, html позволяет указывать к каждой ячейке следующие аттрибуты:
- Объединение ячеек
- Вертикальное и горизонтальное выравнивание
Объединение ячеек выполняется путём указания аттрибутов colspan и rowspan. colspan расширяет ячейку от текущей вправо. rowpspan расширяет ячейку от текущей вниз. По умолчанию оба атрибута равны 1.
Для выравнивания передаётся строка из двух символов. Первый указывает на выравнивание по горизонтали, второй — по вертикали. Для некоторых функций есть по два варианта символа для удобства. Все доступные значения:
- По горизонтали
-
'l' | 's' — текст прижимается к левому краю ячейки, правый край остается неровным (left | start)
'c' | 'm' — текст располагается симметрично относительно центра ячейки (center | middle)
'r' | 'e' — текст прижимается к правому краю ячейки, левый край остается неровным
(right | end)
'j' — текст равномерно распределяется между левым и правым полем, создавая ровные края с обеих сторон (justify)
'd' — как 'j', но дополнительно растягивает даже короткие строки. Например, последнюю строку абзаца (distribute)
- По вертикали
-
't' | 's' — выравнивание по верхнему краю ячейки (top | start)
'c' | 'm' — выравнивание по центру ячейки (bottom | end)
'b' | 'e' — выравнивание по нижнему краю ячейки (bottom | end)
Например, строчка "lc" прижимает текст к левому краю по горизонтали, по вертикали оставляет по середине
Ниже приведена таблица пример по всем атрибутам
# Примерный раздел
Ниже таблица
`table_name: Пример таблицы`
<table>
<thead>
<tr>
<th>№</th>
<th>Название этапа</th>
<th>Исполнитель</th>
<th>Трудоёмкость, чел/дни</th>
<th>Продолжительность работ, дни</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="3" align="em">1</td>
<td rowspan="3">Разработка и утверждение технического задания</td>
<td>Руководитель</td>
<td align="cc">5</td>
<td rowspan="5" align="et">5</td>
</tr>
<tr>
<td></td>
<td></td>
<td>Консультант</td>
<td align="cc">1</td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td>Разработчик</td>
<td align="cc">5</td>
<td></td>
</tr>
<tr>
<td rowspan="2" align="em">2</td>
<td rowspan="2">Технические предложения</td>
<td>Руководитель</td>
<td align="cc">7</td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td>Разработчик</td>
<td align="cm">7</td>
<td></td>
</tr>
<tr>
<td align="em">3</td>
<td>Эскизный проект:</td>
<td></td>
<td></td>
<td rowspan="5" align="ee">16</td>
</tr>
<tr>
<td align="em">3.1</td>
<td>Анализ исходных данных и требований</td>
<td>Разработчик</td>
<td align="cc">9</td>
<td></td>
</tr>
<tr>
<td align="em">3.2</td>
<td>Постановка задачи и цели</td>
<td>Консультант</td>
<td align="cc">1</td>
<td></td>
</tr>
<tr>
<td rowspan="2" align="em">3.3</td>
<td rowspan="2">Разработка описания основного алгоритма</td>
<td>Руководитель</td>
<td align="cc">2</td>
<td></td>
</tr>
<tr>
<td></td>
<td></td>
<td>Разработчик</td>
<td align="cc">7</td>
<td></td>
</tr>
</tbody>
</table>
Макросы
В качестве расширения функционала конвертера библиотекой предусмотрены разные макросы, расширяющие функционал markdown от создания переменных до выполнения кода python. Каждый макрос имеет требуемые права. Список текущих макросов представлен ниже
color
Macros permissions: PASS_ARGUMENTS
Позволяет поменять цвет текста. Цвет задаётся в формате rgb: `color(255,0,0): Красный текст`, `color(0,255,0): Зелёный текст`
Комментарии которые никак не влияют не рендер документа: `comment: Надо будет булочки украсть`
count_appendix
count_images
count_sources
count_tables
Выводит количество всех рисунков/таблиц/формул и других переменных в документ:
Документ включает в себя `count_images` рисунков и `count_tables` таблиц.
count_appendix — количество приложений
count_formulas — количество формул
count_images — количество изображений (картинок)
count_sources — количество источников (номер последнего источника)
count_tables — количество таблиц
Macros permissions: ADD_VARIABLES, PASS_ARGUMENTS
Macros permissions: PASS_ARGUMENTS
formula позволяет генерировать формулы из latex. После этого макроса можно вызывать formula_describe для описания переменных формул
`formula(число ошибок): N=n\x0crac{S}{v}`
`formula_describe(n — найденные собственные ошибки, S — всего внесённых ошибок, v — найденные внесённые ошибки)`
`formula(*число ошибок2): N=2\x0crac{10}{6}=3,(6)`
`formula(число необнаруженных ошибок): (N-n)=3,6-2=1,6`
`formula(формула соотношения): p=\x0crac{1,6}{1,6+K+1}=\x0crac{5}{5+0+1}=0,615`
highlight_color
Macros permissions: PASS_ARGUMENTS
Позволяет поменять цвет фона текста. В качестве аргумента можно использовать только константу из python-docx WD_COLOR_INDEX. `highlight_color(YELLOW): Что-то тут не понравилось. а где задача? Где?`
mention
Macros permissions: READ_VARIABLES, PASS_ARGUMENTS
Позволяет упомянуть рисунок, таблицу или формулу по её названию. Так как данный макрос срабатывает после генерации всего документа, в него нельзя вставить какие-либо макросы, но он позволяет упомянуть любой рисунок/таблицу/формулу, независимо от позиции
Упоминание до: `mention: Главный поток данных`
Неполное упоминание до: `mention: Главный поток`
Упоминание после: `mention: Главный поток данных`
Неполное упоминание после: `mention: Главный поток`
listing
Macros permissions: ADD_VARIABLES, FILE_READING, PASS_ARGUMENTS
Позволяет вставить листинг на месте макроса. Заголовок данным макросом не создаётся. Пример использования:
`listing: ./info.txt`
Если файл, лежащий рядом с main.md и имеющий название info.txt существует, его содержимое будет вставлено в документ в виде листинга.
page_break
Позволяет вставить разрыв в на месте макроса. Служебный макрос.
print_plain_text
Macros permissions: FILE_READING, PYTHON_EXECUTION, PASS_ARGUMENTS
Позволяет выполнить код python, а вывод stdout записать вместо макроса в конечном документе print_plain_text: data_struct_count.py. ВНИМАНИЕ. Данная функция выполняет код python, поэтому в некоторых случаях необходимо ограничить обычных пользователей от этой функции. Выполняется асинхронно (выполняется во время создания docx документа, а результат получается в момент сохранения docx документа).
Структура файлов в примере
├── main.md
├── counter.py
counter.py
for i in range(0,21): print(i, end=',')
main.md
Считаем от 0 до 20: `print_plain_text: counter.py` круто!
Выполняем рендер. Результат в документе docx (Файл out.docx в той же директории): Считаем от 0 до 20: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20, круто!
set_list_digit
Macros permissions: SETTINGS_CHANGE, PASS_ARGUMENTS
set_list_marker
Macros permissions: SETTINGS_CHANGE, PASS_ARGUMENTS
Данные два макроса позволяет менять формат нумерованных и маркированных списков в рендере. MGost не использует встроенные в Docx списки, так как существует некоторые проблемы python-docx в их нумерации, поэтому MGost отсчитывает отступы в автоматическом режиме для следования ГОСТу. У обоих функций следующие аргументы:
- Символ до текста
- Окончание текста (но не последнего в списке!)
- Окончание текста последнего в списке
В отличие от set_list_marker, set_list_digit в первому аргументе можно использовать аргумент counter в фигурных скобках
Пример использования макросов
`set_list_marker(—,;,.)`
`set_list_digit({counter}. ,.,;)`
sources
Macros permissions: READ_VARIABLES
Позволяет вставить список источников, созданный на основе ссылок внутри документа. В качестве первого аргумента можно указать число, с которого начинается отсчёт списка источников (если вы вручную добавляете некоторые источники). Для добавления умных источников в документ обратитесь к этому вопросу
store_var
Macros permissions: ADD_VARIABLES, PASS_ARGUMENTS
store_var_return
Macros permissions: ADD_VARIABLES, READ_VARIABLES, PASS_ARGUMENTS
var
Macros permissions: READ_VARIABLES, PASS_ARGUMENTS
Три данных макроса позволяют создавать и использовать переменные в документе Word. Если у вас какое-то предложение повторяется, его можно сохранить в переменную при первом использовании и повторять в документе далее. В данном случае изменение переменной в одном месте изменит её все использования.
store_var_return
### **Аннотация
В исследовательском разделе `store_var_return(исследовательский_старт): анализируется предметная область, существующие решения, устанавливаются цели, задачи и техническое задание.`
...
# Исследовательский раздел
В данном разделе `var(исследовательский_старт)`
store_var
### **Аннотация
`store_var(исследовательский_старт): анализируется предметная область, существующие решения, устанавливаются цели, задачи и техническое задание.`
В исследовательском разделе `var(исследовательский_старт)`
...
# Исследовательский раздел
В данном разделе `var(исследовательский_старт)`
table_name
Macros permissions: SETTINGS_CHANGE, PASS_ARGUMENTS
Макрос используется перед заданием какой-либо таблицы средствами markdown для её наименования
`table_name: Типы данных динамического объекта`
| Поле | Тип |
|-------------------|---------|
| Позиция | вектор |
| Скорость | вектор |
| Поворот | ротатор |
| Скорость поворота | вектор |
В случае, если рендер встречает таблицу, но не знает её названия, будет вызвано исключение и рендер остановлен
table_of_contents
Macros permissions: READ_VARIABLES
Вставляет содержание на место макроса. Количество использований неограниченно, однако по ГОСТу следует ставить после заголовка "Содержание".
TODO
Макрос-помощник. При встрече рендера с данным макросом MGost удаляет его из документа, но выводит об этом уведомление в stdout. `TODO: доделать макияж`
work_interval
Macros permissions: EDIT_VARIABLES, PASS_ARGUMENTS
Указывает время написания документа. Используется для всего автоматического заполнения, где используются даты (например время обращения к онлайн-ресурсам при заполнении списка источников). Поле значения не используется, однако позволяет передавать от 1 до 2 аргументов. Принимаемые значения по количеству аргументов:
- Начальная дата. Вторая дата устанавливается текущим днём.
- Начальная и конечная дата.
Часто задаваемые вопросы
Где найти полное форматирование Markdown?
MGost следует стандарту GitHub Flavored Markdown. Пример документа с полным функционалом будет позже
Сколько стоит?
По цене 100₽ можно произвести любое количество рендеров в течение часа. При необходимости оплаты всплывает окно с предложением вариантов оплаты. Также предусмотрен единичный рендер по цене 10₽. Все цены продублированы перед оплатой. Перед оплатой удостоверьтесь в цене и получаемом результате.
У меня сломаны номера страниц содержания
Так как содержание рендерится первым, ещё неизвестны номера страниц других заголовков, поэтому Word ставит им 1 по умолчанию. Для обновления номера страниц нажмите CTRL+A (выделить всё) + F9
Как добавить ссылку, чтобы она отобразилась в списке использованных источников?
Для этого используйте в ссылке названеи в квадратных скобках. Пример: [[RL]](https://store.epicgames.com/ru/p/rocket-league). Также допустимо указывать иное название для заполнения в источники, если автоматическое присвоение не работает: [[RL]](https://store.epicgames.com/ru/p/rocket-league "Описание игры Rocket League"). Примеры:
1. В качестве примера можно привести компьютерную игру [[Rocket League]](https://store.epicgames.com/ru/p/rocket-league).
1. В качестве примера можно привести компьютерную игру Rocket League [[*RL]](https://store.epicgames.com/ru/p/rocket-league).
1. В качестве примера можно привести компьютерную игру Rocket League [[*RL]](https://store.epicgames.com/ru/p/rocket-league).
1. В качестве примера можно привести компьютерную игру Rocket League [[*RL2]](https://store.epicgames.com/ru/p/rocket-league "Описание игры Rocket League").
# **Источники
`sources(5)`
Сгенерированный файл Word:
К каждому названию, заключенному
Какие сайты поддерживаются для создания умного содержания?
Все сайты поддерживаются, которые в ответ на запрос заголовка сразу подают полный html файл, без проверок на бота. Расширенный функционал доступен только для сайта arXiv