Shatiy avatar

Eleventy поступово

Теги: it-posts  eleventy-start 

Опис створення блога на Eleventy з теоретичнимі відволіканнями

Для чого це.

Я давнно хотів зробити блог. Я цікавився різними фреймворками. Дивився на next, робив проби на С++...
І ось мені на очі попалася інформація про Elevety - фреймворк для створення статичних блогів, написаниий на JavaScript. По відгуках - він простий і генерує дуже швидкі сайти за рахунок того, що з Elevety ви отимуєте чистий html, який http-сервери віддають дуже швидко.
Я люблю швидкісь як та всім відома мама, тому я вірішив робити сайт на ньому.

В процесі ознайомлення виявилося, що є два фактора, які мені заважають:

  1. Я не знаю JavaScript, тільки поверхово ознайомлювався з ним. А за допомогою JavaScript у Elevety можна робити фільтри, колекції, писати helper-функції і т.д. Без використання JavaScript на Elevety можна робити тільки те, що дозволили розробники. А дозволили вони доволі багато. Тому пробуємо.

  2. Документація. На сайті https://www.11ty.dev є розділ документації і там багато чого є. Але, є велике але. Там нема НОРМАЛЬНОЇ документації.
    Все що є - то якість дурні мануали в яких нема порядку і системності. Їх можна розбити на три групи:

    1. starter. Ці аж надто примітивні, на кшталт: введіть таку команду, створіть такий файл, віиконайте "npx @11ty/eleventy" і ваш перший сайт " hello, wordl" готовий. Нічого більшого, ніж найпростіший блог без пагінації з цього не зробити.

    2. приклади реальних сайтів, де люди описують, як вони розробляли свої сайти. Це подібне до попереднього пункту, але на більш складному рівні, де використовуються специфічні для Elevety можливості. При цьому часто використовується відео. З цього можна отримати багато корисної інформації. От тільки це забирає до біса багато часу, тому що потрібно дивитися повільне відео ангійською, і пробувати допетрити, чого автор зробив якусь дію і що з того він для цього використав є вбудованою можливістю Elevety, а що він дороблював самостійно. В основному там люди документують свої дії, але чому ці дії робляться і звідки що береться - нема.

    3. статті спеціалістів, які стосуються якихось конкретних можливостей і особливостей (на кштадт стоврення користувацьких фільтрів, чи як зробити повний список тегів), де багато специфічної термінології і припускається, що всі основи ви знаєте.

    Нема системної документації від авторів, у якій би розповідалося, як все влаштовано і як працює, а також де розписані всі базові можливості Elevety. Таке враженя, що автори просто забили на документацію, і думають, що користувачі самі у всьому розберуться.

Ну що ж. Спробуємо їм допомогти.

Тому ця стаття, можливо, буде кориса початківцям, які пробують Elevety.

Шаг 1. Встановлення.

Всі команди приводяться для Debian 12

  1. Встановти Node.js версії >= 14:
	sudo apt install nodejs
  1. Створити каталог, де будемо будувати наш сайт (в прикладі це "sample") і перейти в нього
	mkdir sample
	cd sample
  1. Створити у нашому каталозі файл package.json
	npm init -y
  1. Інсталювати Eleventy
	npm install @11ty/eleventy
  1. Перевірка: Запустити Eleventy
	npx @11ty/eleventy

У командному рядку після деякої роботи повинен бути результат

	[11ty] Wrote 0 files in 0.03 seconds (v2.0.1)

Шаг 2. Базове розуміння, як працює Eleventy.

Коли ви запускаєте команду npx @11ty/eleventy, то eleventy обробляє файли і каталоги з вашої потчної папки проекту. Ось так буквально бере кожен файл і аналізує його. Якщо він є файлом того типу, з яким працює Eleventy, то з цього файла Eleventy робе html-файл.

Точніше обробляються файли і каталоги з папки, яка записана у Eleventy-змінну Input. Цю змінну можна задати у файлі ./.eleventy.js (якщо його нема, то потрібно створити). По замовчуванню це папка проекту. Часто її переназначають на папку src у папці проекту. Для цього у цей файл .eleventy.js потрібо добавити рядок "Input directory: src". Тоді .eleventy.js буде таким:

	module.exports = function (eleventyConfig) {
	  Input directory: src<br>
	}

Обробка файлів полягає в створенні html-файлів з ваших фалів, які лежать у Input. html-файли, які створюються, складаються в папку _site у вашій поточній папці проекту. Цю папку, як і майже все у Eleventy, також можна переназначити.

Як створюються html-файли.

  1. З кожного файла (того типу, який підтримується eleventy) який лежить у Input створюється окремий html-файл з тим же іменем і розширенням html. Це ім'я при потребі можна змінювати за допомогою "FrontMatter-змінних". Про це буде далі.
  2. Файли, які лежать у підпапках (найчастіше це md-файли) також обробляються: з них створюються html-файли і складаються у відповідні підпапки у папці _site з тими ж іменами.

Простий приклад:

  1. Якщо ви у вашій потчній папці проекту створите файл простий файл класичний index.html, то, після виконання "npx @11ty/eleventy" він практично без змін опинится в папці _site.

  2. Якщо ви у вашій потчній папці проекту створите файл файл index.md, то, після виконання "npx @11ty/eleventy" в папці _site опинится файл index.html, який створиться з index.md за певними правилами.

Це нам дає небагато користі, але ми побачили, що відбувається. Щоб зробити щось більше, ми повинні використовувати шаблони, з яких зможуть ствроюватись більш складні файли.

Що таке FrontMatter чи Front Matter.

Front Matter - це частина файла, яка знаходиться на початку файла, обрамляється рядками "---" і відділяється від подальшого (основного) змісту файла пустим рядком. Наприклад:

---
title: Приклад Front Matter 
---

Текст Текст Текст Текст Текст
Текст	Текст	Текст	Текст

В цьому прикладі Front Matter - це частина

---
title: Приклад Front Matter 
---

і у ній визначається змінна title, яка може використовуватись в основній частині файла в подвійних фігурних дужках.

Фішка Eleventy полягає в тому, що він має можливості для легкого сворення блога і зроблений за принципами "zero-config" і "data-driven". "zero-config" означає, що для створення працюючого сайту вам достатньо конфігурації по замовчуванню. Але щоб зробити сайт, вам потрібно знати що це за конфігурація, куди класти ваші файли і що буде відбуватись. "data-driven" означає "керується даними". Ви можете визначати як буде вести себе і як буде виглядати ваш сайт, що основні

Означає тце наступне:

  1. Фіксована структура директорій сайта. Eleventy по замовчуванню використовує наступну структуру директорій:
назва шлях Опис
Input ./ Тут знаходяться всі файли і директорії, які Eleventy використовує як вхідні дані
Data ./_data/ Папка, де лежать файли, в котрих зберігаються глобальні дані для сайта.
Наприклад, якщо маємо файл ./_data/data1.md наступного змісту:
---
slogan: "Вперед і вверх"
cost: 238.20
---
то змінні slogan і cost з відповідними значеннями будуть доступні в будь-якімй частині шаблону сайту
Includes ./_includes/ Папка, де лежать часини шаблону сайта.

Якщо ми в ./_includes/ помістимо, наприклад, файл шаблону layout.njk, то включаючи у Front Matter будь якого md-файла даних рядок «layout: "layout.njk"» ми ми добиваємося того, що при обробці цього файла буде використовуватись цей шаблон layout.njk настуним чином:

Результуючий html-файл починає формуватися з layout.njk.
Все що є html-розміткою в layout.njk буде включено в результуючий файл без змін.
Все, що відноситься до шаблонних частин (як от змінні {{ змінна }} чи діі {% if %} - {% endif %} і т.п.) - оборобляється відповідно до правил шаблонізатора.
Основна частина md-файла може вкоючатись у результуючий файл за допомогою змінної {{ content }}
Layouts false Папка, де лежать часини шаблону сайта. В чому відмінність від Includes не розібрався.
Output ./_site/ Папка, де опиняеться наш результуючий файл

  1. Eleventy по замовчуванню обробляє наступні формати: liquid,md,njk,html,11ty.js

  2. Створення колекції з md-файлів конкретної директорії і можливість роботи з елементами цієї колекції через через шаблонні вирази. Можна в циклі перебрати всі елементи колекції і виконати якісь дії

Він надає можливості для:

  1. Обробки великої кількості файлів у підпапках сайта
  2. Створення html-списків з посиланнями на файли з п.1, що потрібно для блога
  3. Пагінації. Іншими словами, він може списки з п.2 розбити на порції (сторінки), щоб сторінка вміщалася на екран з вбудованимим можливостями посилань на попередню і наступну сторінку.
  4. Додавання тегів до записів блога, з вбудованимим можливостями посилань на списки статей з відповідними тегами.
  5. Створення меню з посиланнями на списки з п.2 чи п.3.
  6. Вільного формування html-сторінок з допомогою шаблонів.

Цього вже достатньо щоб зробити доволі продвинутий блог.

Тепер подивимось, як цим кортистуватися.

Свої статті я буду робити у вигляді md-файлів

При обробці файлів Eleventy зчитує змінні з розділу "Front Matter" і може вільно їми оперувати у шаблонах.

Шаблони.

Шаболни - це html-сторінки, чи їх частини, з додатковими спеціальними конструкціями. Вони використовуються для генерації остаточних html-файлів.

Eleventy може використовувати різні мови шаблонів: HTML (.html), Markdown (.md), WebC (.webc), JavaScript (.11ty.js), Liquid (.liquid), Nunjucks (.njk), Handlebars (.hbs), Mustache (.mustache), EJS (.ejs), Haml (.haml), Pug (.pug), TypeScript (.ts), JSX (.jsx), MDX (.mdx), Custom (.).
Як на мене - це забагато. Достатньо було б дві чи три. І кращу документацію, ніж є. Але у авторів своя думка.

Я буду використовувати мову шаблонів Nunjucks, тому, що більшість прикладів, які є на сайті https://www.11ty.dev використовують саме її.

Щоб зробити Nunjucks-шаблон, треба у будь-який html-файл вставити Nunjucks-конструкції.

Nunjucks-конструкції всередині html-файла обрамляются наступними парами симвлолів: {{ }} і {% %}. З допомогою {{ }} можна виводити значення змінних, а з допомогою {% %} - виконувати дії.

Основні Nunjucks-конструкції:

  • {{ змінна }}, де змінна - це eleventy-змінна.
    Eleventy-змінні можуть бути вбудованими, можуть отримуватися з FrontMatter-частин файлів даних, з програм JavaScript та з інших джерел, які я ще не всі знаю, а також можуть бути створеними вами вручну.
    Якщо така конструкція зустрічається у шаблоні, то вона заміняється на значення змінної.

  • {{ змінна | фільтр }} , де змінна - та ж, що вище, а фільтр - функція, яка обробляє занчення, записане у змінну.
    У Nunjucks є доволі багато вбудованих фільтрів. Наприклад:
    abs, capitalize, dictsort, escape, join, last, length, lower, replase, reverse, sort та інші.
    Крім того є можливість створювати фільтри самостійно. Доволі часто саморобні фільтри використовують для відображення дати у потрібному форматі.

  • {% вираз %} , де вираз - це команда Nunjucks.

    Основні команди Nunjucks:

    • set - присвоювання значення змінній
    • extends - вказує на базовий (батьківський) шаблон, який ми будемо модифікувати
    • block - endblock - визначає розділ шаблону та присвоює йому ім'я.
      Це використовується при успадкуванні шаблону. Базові шаблони можуть визначати блоки, а дочірні шаблони можуть перевизначати їх новим вмістом.
    • include - доволяє вставити один файл шаблону в інший
    • import - подібно до include, але є відмінності. import завантажує інший шаблон і дозволяє отримати доступ до його експортованих значень.
      Макроси і присвоєння верхнього рівня (зроблені за допомогою set) експортуються з шаблонів, що дозволяє отримати доступ до них в іншому шаблоні. Імпортовані шаблони за замовчуванням обробляються без поточного контексту, тому вони не мають доступу до жодної зі змінних поточного шаблону.
    • if - endif - Команда умовного виконання (виводу). Якщо умови виконуются, то те що знаходится до endif виводится у html-файл. Інакше - не виводиться.
    • for - endfor - Команда цикла. Перебирає елементи масиву чи словаря і виконує якісь дії.
      Наприклад, якщо в нас є колекція (або ж масив) items (що таке колекції - далі), з настуними значеннями поля title: "title 1", "title 2", "title 3" і так далі, то включення в шаблон наступного коду:
	<ul>  
		{ % for item in items \%\}  
		  <li>\</li>  
		\{\% endfor \%\}  

	</ul>

Приклад створення простого шаблону.

Нижчевказані файли потрібно покласти в директорію ./_includes/
Примітка: просте копіювання нижчевказаного текста не спрацює, тому що спеціальні nunchucks-послідовності , , і я вставив як картинки. Інакше вони не вставляються, тому що Eleventy їх обробляє. Так що спеціальні послідовності вам доведеться вставляти вручну.

Файл "layout.njk":

---
title: My site TITLE
site:
    name: My site NAME
---

<!DOCTYPE html>
<html lang="uk">

include "head.njk"
include "top.njk"
include "main.njk"
include "bottom.njk" 

</body>
</html>

Тут ми створюємо основний шаблон, в який вставляємо чотири частини нашого файла, які описуються шаблонами: "head.njk" - в ньому описується розділ ... нашого результуючого html-файла "top.njk" - в ньому описується верхня частина нашого результуючого html-файла "main.njk"- в ньому описується середня частина нашого результуючого html-файла "bottom.njk" - в ньому описується нижня частина нашого результуючого html-файла



Файл "head.njk":

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title></title>
  \{\% include "partials/meta-info.njk" \%\}
  <link rel="shortcut icon" href="/images/avatar.svg" type="image/x-icon">
  <link rel="stylesheet" href="/style.css">
</head>

Файл "top.njk"

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title></title>
  \{\% include "partials/meta-info.njk" \%\}
  <link rel="shortcut icon" href="/images/avatar.svg" type="image/x-icon">
  <link rel="stylesheet" href="/style.css">
</head>

Файл "main.njk" Файл "bottom.njk"







Усі теги:
 commons  
 ідея  
 думка  
 сюжет  
 it-posts  
 eleventy-start  
 humors  
 ru  
Інтелектуальна власність
Зроблено Сергієм Шатнім у 2024 році з використанням Eleventy.
Пишіть