keystone ssg

Предупреждение

Keystone в наши дни выглядит устаревшим, я бы порекомендовал вам вместо этого взглянуть на Astro или Vite.

---

Почему Кистоун?

Keystone — генератор статических сайтов, идеально подходящий для быстрого создания небольших веб-сайтов. Никакой настройки не требуется, а набор удобных функций включен по умолчанию.

Функции

• Простая установка и настройка, одна команда и готово к работе
• Автоматическое обновление сервера разработки
• Используйте шаблоны и повторно используемые фрагменты/импорт со слотами.
• Автоматическая маршрутизация, просто загрузите /public и все готово.
• Поддержка Babel, SCSS и Markdown включена по умолчанию, исходные карты в режиме разработки.
• Минимизация и объединение JS и CSS (с помощью Rollup)
• Динамическая загрузка ссылок (без перезагрузки страницы)
• Генератор индексных файлов поиска для удобного поиска по веб-сайтам

Начиная

Установить

Создайте новый каталог и выполните следующую команду, чтобы настроить Keystone, package.json и git. Требуется узел 14.xx.

 $  npm install keystone-ssg

Отлично, вы установлены!

Сервер разработки

Запустите сервер разработки Keystone, а затем перейдите по адресу http://localhost:8080, чтобы просмотреть пример веб-сайта.

 $ npm run dev

Создать проект

После запуска команды проект создается в папке /public и готов к загрузке.

 $ npm run build

Создание вашего веб-сайта

В проекте Keystone есть шесть важных каталогов, каждый из которых имеет свою цель:

Страницы

Каждый файл HTML .html и markdown .md в папке страниц соответствует странице вашего веб-сайта. Здесь есть два файла в примере проекта, попробуйте открыть index.html . Автоматическая маршрутизация будет связывать файлы в папку /public при запуске npm run build следующим образом:

 /pages/index.html   ->  /public/index.html
/pages/example.md ->  /public/example/index.html

Возможно, вы заметили, что index.html имеет следующий тег: <_template basic.html /> . При этом содержимое index.html помещается в файл шаблона с слотами по адресу /templates/basic.html . Этот пользовательский формат тегов HTML работает и внутри файлов .md .

Шаблоны

Шаблоны можно использовать с /pages , чтобы создать готовую основу для ваших страниц. Используйте тег <_slot /> в файле шаблона, чтобы предоставить точку входа для вашего контента. Откройте /templates/basic.html и найдите:

 < _var title default="Keystone default title" />

Это слот переменной с именем title в файле шаблона с необязательным значением по умолчанию.

Использование следующего тега шаблона внутри /pages позволит вам ввести в шаблон собственное значение со страницы контента:

 < _template basic.html title="A custom title" /> 

Компоненты

Папка /components просто используется для повторно используемых компонентов. Тег <_import> используется для импорта компонентов в другие файлы HTML, пример которых находится внутри /templates/basic.html .

 < _import header.html />

Тег <_import> также можно использовать для импорта содержимого любого другого типа файла (JS, SCSS и т. д.) после предварительного объединения источника.

источник

Поместите файлы Javascript в папку /src . Следующий тег будет преобразован в обычный тег импорта <script> , ссылающийся на ваш файл /src/main.js :

 < _script main.js />

Импорт ES6 полностью поддерживается, и полученный файл будет транспилирован с помощью Babel, объединен с Rollup и минимизирован.

Стили

Папка /styles используется для вашего CSS/SCSS. Следующий тег будет преобразован в обычный тег импорта CSS <link> , ссылающийся на ваш скомпилированный файл /styles/main.scss :

 < _style main.scss />

Все функции node-sass полностью поддерживаются, включая @import .

Ресурсы

Здесь размещаются статические ресурсы, то есть шрифты, изображения, значки. Здесь все будет перенесено в соответствующую папку в корневом каталоге, например:

 /assets/favicon.ico -> /public/favicon.ico
/assets/fonts/fontname.ttf -> /public/fonts/fontname.ttf

Примечания

Ключевые HTML-теги

• Каждый пользовательский HTML-тег Keystone можно использовать в любом месте HTML-файла, даже в других атрибутах HTML, помимо других тегов Keystone.
• Альтернативно для всех пользовательских тегов Keystone вы можете использовать атрибут src для указания файла в любой папке: <_template src='myfolder/myfile.html' /> .
• Все пути указаны относительно папки, содержащей package.json , не используйте начальную косую черту, если вы не хотите получить доступ к файлу за пределами проекта.
• В атрибутах HTML-тега Keystone можно использовать одинарные, двойные кавычки или обратные кавычки.

Динамическая загрузка

• Динамическая загрузка извлекает ссылку на локальный веб-сайт и заменяет содержимое текущей страницы новой без перезагрузки и переключения страниц.
• Когда динамическая загрузка включена, состояние страницы (например, введенные значения, положение прокрутки) не сохраняется при использовании кнопки «Назад».
• При нажатии на ссылку класс .keystone-page-loading настроен на display: block . Если в CSS для класса установлено значение display: none , это можно использовать для создания индикатора загрузки.
• Отключите динамическую загрузку в keystone.config.js.

Генератор поискового индекса

• Генератор поискового индекса создает файл search.json в корневом каталоге. Это массив JSON, содержащий объект для каждой страницы, в котором перечислено текстовое содержимое, заголовок и путь к странице.
• Все HTML-теги удаляются со страницы, и сохраняется только текст.
• Этот файл можно получить и запросить с помощью функции поиска на веб-сайте, чтобы легко найти, какая страница содержит какой контент.
• Отключите помощник панели поиска в keystone.config.js.

Разнообразный

• public папка игнорируется Git, удалите public строку из .gitignore если вы хотите использовать ее для фиксации в Git.

Обновление Keystone

• Замените номер версии в package.json версией, до которой вы обновляетесь, и запустите npm install keystone-ssg для быстрого обновления.

API

Теги

Ярлык	Описание	Атрибуты
<_template>	Импортирует текущий файл в <_slot> в файле шаблона.	[имя файла], [имя переменной], источник
<_slot>	Используется в файле шаблона в качестве точки входа для импортированного файла.	Никто
<_var>	Используется в файле шаблона для замены переменной, взятой из <_template>	[имя переменной], по умолчанию
<_import>	Импортирует компонент	[имя файла], источник
<_script>	Создает тег <script> ссылающийся на встроенный скрипт.	[имя файла], источник
<_style>	Создает тег <link> , ссылающийся на связанный файл CSS.	[имя файла], источник

НПМ-команды

Команда	Описание	Выходные различия
npm run dev	Создает веб-сайт для разработки, затем запускает сервер разработки Keystone.	Создаются встроенные исходные карты. Внедряется скрипт сервера разработки.
npm run build	Создает сайт для производства.	Бандл сжат и минифицирован.

Конфигурационный файл

Файл конфигурации — keystone.config.js

Вариант	Описание	По умолчанию
динамические ссылки	Обеспечивает динамическую загрузку локальных ссылок на вашем веб-сайте Keystone без необходимости обновления.	истинный
поискФайл	Создает search.json в корневом каталоге.	истинный
индексный путь	Корневой каталог вашего сайта	'/'
порт	Порт сервера разработки, localhost: 8080.	8080
портВС	Второй порт, используемый для сервера разработки.	8081
девсерверип	Местоположение сервера разработки: localhost : 8080. Замените локальный IP-адрес вашего устройства, чтобы просмотреть сервер разработки на локальных устройствах (пример: «192.168.1.103»).	'локальный хост'
смотрел	Каталоги, отслеживаемые сервером разработки Keystone, которые вызывают перекомпиляцию и обновление страницы при редактировании файлов.	['шаблоны', 'страницы', 'активы', 'компоненты', 'источник', 'стили']
строить	Каталог страницы контента	"страницы"
служил	Каталог, содержащий сгенерированный веб-сайт	'общественный'
полная перекомпиляция	Принудительно выполнить полную перекомпиляцию всех файлов после каждого изменения файла в режиме разработки.	ЛОЖЬ

Структура каталога по умолчанию

 | empty-keystone-project
--| .git/
--| assets/
--| components/
--| pages/
--| src/
--| styles/
--| templates/
--| keystone.config.js
--| package.json
--| package-lock.json

Ошибка плагина

Если после установки и запуска примера у вас возникла ошибка PLUGIN_ERROR, это проблема Babel, для ее устранения выполните следующую команду:

 npm install @babel/core @babel/preset-env --save-dev