Возможности:
- подстановка кусков маркдауна
- автонумерация (например рисунков)
- вставка содержимого других файлов (например исходного кода программы)
Термины:
- кусочек - файл, который находится в папке с шаблонами
- основной шаблон - файл с расширением .tpl.md, который мы хотим превратить в простой .md
Язык регистрозависимый. ПРИВЕТ и ПрИвЕт не одно и то же в рамках языка.
Рекомендуется называть ваш основной шаблон используя расширение .tpl.md, это позволит вам разместить рядом с ним простой .md файл.
После того как вы скачали репозиторий, используйте скрипт md_tpl.py для препроцессинга. Это будет выглядеть так:
python путь/к/md_tpl.py аргументыПодробнее про аргументы скрипта (цифра - порядковый номер передачи скрипту):
- Путь к основному шаблону
- Путь для вывода маркдауна
То есть перевод основного шаблона в маркдаун выглядит так (допустим у нас файл README.tpl.md и все файлы в текущей директории):
python ./md_tpl.py ./README.tpl.md ./README.mdДополнительные аргументы (каждый из них имеет формат --аргумент=значение):
--template_folder=путь/к/папке/кусочков - указывает путь к папке кусочков (шаблонов). По умолчанию используется папка markdown_templates, которая находится рядом со скриптом md_tpl.py. Если будете перемещать скрипт не забудьте и папку или укажите к ней путь через этот аргумент скрипта.
Для вставки переменной используется следующий синтаксис:
{ название_переменной }
Кусочки - куски маркдауна, которые можно легко вызывать в основном шаблоне и в самих кусочках. Все кусочки должны лежать в одной папке. Название файла кусочка определяет его называние для вызова. Для вызова кусочка используется вот такой синтаксис:
(( название_кусочка = переменная1: "значение 1", переменная2: "значение 2", ... ))
После знака = идут переменные в формате JSON: ключ: "значение". Для упрощения синтаксиса ключи (названия переменных) идут без кавычек. Нельзя передавать массивы и другие объекты как значения переменных, однако переменные могут иметь любые названия, например : или + или другие спец. символы.
Однако есть одна специальная переменная - =. Использование этой переменной позволяет писать короче.
(( кусочек = =:"значение" ))
Можно записать так:
(( кусочек == "значение" ))
Такой синтаксис не запрещает другие переменные, например:
(( картинка == "./путь/к/картинке.jpg", заголовок: "заголовок картинки" ))
В таком случае у нас будет две переменных внутри кусочка: = и заголовок.
Можно писать вызов кусочков в несколько строк:
((
кусочек =
переменная1: "значение1",
переменная2: "значение2"
))Главное чтобы все запятые стояли на месте, иначе вы получите ошибку.
Какие переменные будут подставлены в итоге зависит только от того что вы напишете в кусочек. Если в кусочек передана переменная, которая не используется в нём, она будет проигнорирована.
В основном шаблоне можно использовать только вызов кусочков.
В самих кусочках можно вставлять переменные.
Вставка специальных директив выглядит как вставка переменных, только каждая директива начинается со знака $:
{ $директива }
Директивы могут принимать параметры вот так:
{ $директива(параметры) }
Похоже на вызов функции.
Список директив:
$n- номер кусочка этого типа. Если наш кусочек картинка с автонумерацией, то используйте{$n}, чтобы добавить автономер.$args- подставляет все аргументы текущего кусочка. Эта директива используется для вызова одного кусочка внутри другого и передачи аргументов "из вне".$file(путь)- подставляет содержимое файла по указанному пути. Путь рассматривается относительно основного шаблона.
В остальном этом простой маркдаун. Надеюсь вы знаете, что в маркдауне можно писать HTML код, поэтому MD_TPL удобно использовать чтобы обуздать куски HTML, и убрать его из основного шаблона.
Во всех примерах в качестве основного шаблона будет выступать файл BASE.tpl.md, вывод происходить в OUTPUT.md, а кусочки будут лежать в папке markdown_templates.
В репозитории уже есть готовые шаблоны, используйте их на своё усмотрение.
Картинка с автонумерацией и заголовком
<!-- markdown_templates/image.md -->
<p align="center">
<img src="{src}"><br>
Рисунок №{$n} - {title}
</p><!-- BASE.tpl.md -->
Это приложения к дипломной работе:
(( image = src:"./01.jpg", title:"Первая картинка" ))
((
image =
src:"https://longlonglonglonglong.domain/path/to/image.jpg",
title:"Вторая картинка"
))<!-- OUTPUT.tpl.md -->
Это приложения к дипломной работе:
<p align="center">
<img src="./01.jpg"><br>
Рисунок №1 - Первая картинка
</p>
<p align="center">
<img src="https://longlonglonglonglong.domain/path/to/image.jpg"><br>
Рисунок №2 - Вторая картинка
</p>Раскрывающийся блок
<!-- markdown_templates/toggle{.md -->
<details><summary>{=}</summary><!-- markdown_templates/toggle}.md -->
</details><!-- BASE.tpl.md -->
Ниже представлен исходный код hello world на с++:
(( toggle{ == "Исходный код" ))
```c++
#include <iostream>
int main() {
std::cout << "Hello, World!";
return 0;
}
```
(( toggle} ))<!-- OUTPUT.tpl.md -->
Ниже представлен исходный код hello world на с++:
<details><summary>Исходный код</summary>
```c++
#include <iostream>
int main() {
std::cout << "Hello, World!";
return 0;
}
```
</details>Раскрывающийся блок c картинкой
<!-- markdown_templates/image.md -->
<p align="center">
<img src="{src}"><br>
Рисунок №{$n} - {title}
</p><!-- markdown_templates/toggle.md -->
<details><summary>{=}</summary>
(( {:} = {$args} ))
</detail><!-- markdown_templates/toggle-image.md -->
((
toggle == "Открыть изображение",
::"image"
src:"{src}",
title:"{title}"
))<!-- BASE.tpl.md -->
Теперь мои картинки такие компактные:
(( toggle-image = src:"one.jpg", title:"Первый рисунок" ))
(( toggle-image = src:"two.jpg", title:"Второй рисунок" ))На первом шаге происходит вот такая замена:
<!-- OUTPUT.tpl.md -->
Теперь мои картинки такие компактные:
((
toggle == "Открыть изображение",
::"image"
src:"one.jpg",
title:"Первый рисунок"
))
((
toggle == "Открыть изображение",
::"image"
src:"two.jpg",
title:"Второй рисунок"
))Вторым шагом подключается toggle:
<!-- OUTPUT.tpl.md -->
Теперь мои картинки такие компактные:
<details><summary>Открыть изображение</summary>
((
image =
=:"Открыть изображение",
::"image",
src:"one.jpg",
title:"Первый рисунок"
))
</detail>
<details><summary>Открыть изображение</summary>
((
image =
=:"Открыть изображение",
::"image",
src:"two.jpg",
title:"Второй рисунок"
))
</detail>Дальше используется шаблон картинки. Все аргументы, которые в нём не используются, игнорируются. Таким образом на шаблон картинки оказывают влияние только src и title:
<!-- OUTPUT.tpl.md -->
Теперь мои картинки такие компактные:
<details><summary>Открыть изображение</summary>
<p align="center">
<img src="one.jpg"><br>
Рисунок №1 - Первый рисунок
</p>
</detail>
<details><summary>Открыть изображение</summary>
<p align="center">
<img src="two.jpg"><br>
Рисунок №2 - Второй рисунок
</p>
</detail>Вставка исходного кода из файлов программы
<!-- markdown_templates/file.md -->
{$file({=})}// Human.h
class Human {
public:
int age;
Human(int humanAge);
}// Human.cpp
#include "Human.h"
Human::Human(int humanAge) {
age = humanAge;
}<!-- BASE.tpl.md -->
Был разработан класс Human:
```c++
(( file == "Human.h" ))
```
```c++
(( file == "Human.cpp" ))
```<!-- OUTPUT.tpl.md -->
Был разработан класс Human:
```c++
class Human {
public:
int age;
Human(int humanAge);
}
```
```c++
#include "Human.h"
Human::Human(int humanAge) {
age = humanAge;
}
```Некоторые из примеров выше повторяют файлы из папки markdown_templates из репозитория.
Главной целью этого препроцессора является максимально повысить читабельность маркдауна в любых ситуациях.
Если найдёте баг пишите в issues.