Pug
Использование шаблонизатора pug в сборке.
Gulp таск
Файлы шаблонизатора pug собираются таском ./gulp/tasks/pug.js.
Иерархия файлов
Файловая структура pug выглядит следующим образом:
./src/pug/
├── components
├── data
├── layouts
├── markdown
├── pages
├── parts
└── README.md
- components - содержит миксины часто встречаемых элементов на сайте;
- data - содержит переменные и различные данные для вывода на сайте;
- layouts - содержит шаблоны из которых собираются страницы сайта;
- markdown - содержит документы в формате .md для последующего подключения их содержимого на страницах;
- pages - содержит отдельные страницы проекта;
- parts - содержит общие, повторяющиеся для всех страниц элементы, такие как шапка, подвал сайта и т.п.
Каталог components
Как создаются миксины в pug можно узнать на официальном сайте шаблонизатора.
Пример создание миксина:
// Файл title.pug
mixin h2(title, link)
h2(id=link)
a(href="#" + link, aria-label="Ссылка на раздел: " + title)
Пример вызова миксина:
include ../components/title.pug
+h2("Заголовок", "http://link...")
Каталог data
Как создаются переменные в pug можно узнать на официальном сайте шаблонизатора.
Пример создание переменных:
// Файл config.pug
- const siteVersion = "1.0";
- let siteVersion = "1.0";
- var siteVersion = "1.0";
Пример вызова переменных:
p #{siteVersion}
p Некий текст #{siteVersion}
p(class=siteVersion)
Для того чтобы pug мог работать с json данными необходимо его настроить. Реализация настройки содержится в файле ./gulp/tasks/pug.js:
const getData = () => {
const dir = config.src.pug.data
const files = fs.readdirSync(dir)
const data = {}
files.forEach(file => {
if (!file.endsWith('.json')) return
const fileName = file.replace('.json', '')
data[fileName] = JSON.parse(fs.readFileSync(`${dir}/${file}`, 'utf8'))
})
return data
}
Предположим имеется файл ./src/pug/data/mainNav.json с содержимым:
{
"title": "Вводная информация",
"icon": "icon-book",
"links": [
{
"name": "Справочник терминов",
"link": "intro/index.html"
},
{
"name": "Иерархия файлов",
"link": "intro/hierarchy.html"
}
]
}
Логика работы следующая:
-
В каталоге data выбираются все файлы с расширением json;
-
Cодержимое файлов помещается в переменную jsonData с ключом название файла, например:
имя файла mainNav.json
переменная jsonData["mainNav"] = содержимое файла mainNav.json -
Чтобы получить значение обращаемся к переменной jsonData:
p #{jsonData.mainNav.title}
p #{jsonData.mainNav.icon}
each link in jsonData.mainNav.links
p #{link.name}
Каталог layouts
Как создаются шаблоны в pug можно узнать на официальном сайте шаблонизатора.
Пример создание шаблона:
include ../data/*.pug
include ../components/*.pug
block variables
- var pageTitle = "Укажите заголовок";
doctype html
html.no-js(lang="ru")
head
include ../parts/head.pug
body
div(hidden)
include ../../assets/icons/sprite-mono.svg
include ../../assets/icons/sprite-multi.svg
.container
block header
include ../parts/header.pug
main.main-content
.main-content__intro
block intro
.main-content__toc
.main-content__toc-wrapp
block toc
strong Оглавление страницы:
.main-content__content
block content
block scripts
script(src="js/main.js?v=" + siteVersion, type="module")
Каталог markdown
Как использовать markdown разметку в pug можно узнать на официальном сайте шаблонизатора здесь и здесь.
Пример создание markdown разметки:
# Заголовок H1
### Заголовок H3
**Жирный текст**
- Элемент списка 1
- Элемент списка 2
[[Ctrl]] + [[K]]
Вывести markdown разметку в шаблоне pug можно двумя способами:
- Прописать непосредственно в самом файле:
:markdown-it
НИЖЕ ИДЕТ MARKDOWN РАЗМЕТКА с оборачивание в тег <p>
:markdown-it(inline)
НИЖЕ ИДЕТ MARKDOWN РАЗМЕТКА без оборачивание в тег <p>
- Подключить отдельный файл:
include:markdown-it ../markdown/docs.mdКаталог pages
Как создаются страницы в pug можно узнать на официальном сайте шаблонизатора.
Пример создание страницы:
extends ../layouts/default.pug
block variables
- var pageTitle = "Документация";
- var pageDesc = "Описание по разворачиванию сборки проекта и дальнейшей его поддержки.";
block intro
h1 #{ pageTitle }
p #{ pageDesc }
block append toc
:markdown-it
- [Начало работы](#start)
block content
+h2("Начало работы", "start")
:markdown-it
Данный раздел содержит информацию по установке необходимых программ для работы над проектом, на различных операционных системах.
Каталог parts
Как используются повторяющиеся части страницы в pug можно узнать на официальном сайте шаблонизатора.
Пример создание страницы:
// Файл head.pug
- var siteTitle = pageTitle ? `${pageTitle} — ${siteTitle}` : siteTitle;
- var siteDescription = pageDesc ? pageDesc : siteDescription;
meta(charset="UTF-8")
meta(http-equiv="X-UA-Compatible", content="IE=edge")
meta(name="viewport", content="width=device-width, initial-scale=1")
title #{ siteTitle }
meta(name="description", content=siteDescription)
meta(name="theme-color", content=siteColor)
link(rel="mask-icon", href="favicons/favicon.svg", color=siteColor)
link(rel="manifest", href="manifest.json")
link(rel="apple-touch-icon", href="favicons/apple-touch-icon.png")
link(rel="shortcut icon", href="favicons/favicon.ico", type="image/x-icon")
link(rel="stylesheet", href="css/style.css?v=" + siteVersion)
link(rel="preload", href="fonts/roboto/roboto-light.woff2", type="font/woff2", as="font", crossorigin="anonymous")
link(rel="preload", href="fonts/roboto/roboto-regular.woff2", type="font/woff2", as="font", crossorigin="anonymous")
link(rel="preload", href="fonts/roboto/roboto-medium.woff2", type="font/woff2", as="font", crossorigin="anonymous")
Пример подключение страницы:
html.no-js(lang="ru")
head
include ../parts/head.pug
Дополнительный функционал
Pug позволяет создавать свои пользовательские фильтры наподобии фильтра markdown-it, инструкцую по фильтрам можно почитать на официальном сайте.
В данной сборке используется js плагин highlight.js для подсветки кода, но он не позволяет размещать разметку html без экранирования тегов. Средствами pug экранировать не удалось, поэтому в gulp таске pug.js была созданна пользовательская функция special-chars.
Пример ее работы, здесь мы вставляем html разметку так как она есть, без экранирования:
+code("pug")
:special-chars
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
</head>
<body>
</body>
</html>
На выходе получаем экранируемый код, который корректно отображается в highlight.js:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
</head>
<body>
</body>
</html>