#tw_api_jekyll
Привет. Продолжаем знакомство с Jekyll. В прошлый раз мы «подготовили почву» для нашего сайта-справочника.
Сегодня:
- добавим шаблон для сайта,
- добавим источник (спецификацию в формате Open API), из которого будет собираться справочник,
- хоть в каком-нибудь виде выведем содержимое спецификации на сайт.
1. Добавление шаблона
Чтобы добавить шаблон для нашего сайта, сделайте следующее:
1.1. Создайте в корне директории с сайтом папку _layouts. Именно в ней по умолчанию Jekyll ищет шаблоны для страниц сайта.
1.2. Создайте в этой папке файл api_layout.html со следующим содержимым:
` page`.`title `
` content `
1.3. В файле index.md (его мы создали в прошлый раз и «отвязали» от шаблона по умолчанию), в frontmatter укажите, что для этой страницы будет использоваться шаблон api_layout.html:
---
layout: api_layout
---
2. Добавление спецификации, из которой будет собираться справочник
Чтобы добавить спецификацию, сделайте следующее:
2.1. Создайте в корне репозитория с сайтом папку _data. Это папка, которая предназначенная для хранения структурированных данных в форматах YAML, JSON или CSV. Очень удобно, чтобы разделить контент, который нам нужно рендерить, от шаблонов, скриптов и пр.
2.2. В папке _data создайте файл openapi_spec.yaml.
2.3. В файл openapi_spec.yaml поместите спецификацию (эту спецификацию мы с вами разработали на Курсе по проектированию и документированию API). Скопировать ее можно здесь.
3. Вывод содержимого спецификации на сайт
Чтобы вывести спецификацию на сайт, сделайте следюущее:
3.1. Создайте в корне репозитория с сайтом папку _includes. В Jekyll эта папка используется для хранения переиспользуемых фрагментов кода.
3.2. В папке _includes создайте файл api_reference.liquid. Его как раз мы и будем потом переиспользовать. Здесь будет находиться скрипт для вывода содержимого спецификации на страницу с необходимыми преобразованиями. Подробнее про Liquid — в документации.
3.3. В файл api_reference.liquid добавьте код для вывода содержимого спецификации openapi_spec.yaml на страницу сайта:
{% assign spec = site.data.openapi_spec %}
` spec `
3.4. В файл index.md добавьте код, который как раз и будет переиспользовать наш шаблон api_reference.liquid:
{% include api_reference.liquid %}
При рендеринге страницы Jekyll дойдет до этого кода, увидит там include, пойдет в папку _include и выполнит liquid-скрипт в файле api_reference.liquid.
Готово, если вы все сделали правильно, содержимое спецификации появится на странице сайта (не забываем, что рендеринг запускается командой bundle exec jekyll serve).
Да, выглядит это пока некрасиво (но главное — что содержимое спецификации выводится на страницу). Но все еще впереди. Красоту будем наводить в следующих постах.
Свериться с результатом, который должен у вас появиться, можно в ветке iteration_2 репозитория, специально подготовленного под текущую серию постов.
Привет. Продолжаем знакомство с Jekyll. В прошлый раз мы «подготовили почву» для нашего сайта-справочника.
Сегодня:
- добавим шаблон для сайта,
- добавим источник (спецификацию в формате Open API), из которого будет собираться справочник,
- хоть в каком-нибудь виде выведем содержимое спецификации на сайт.
1. Добавление шаблона
Чтобы добавить шаблон для нашего сайта, сделайте следующее:
1.1. Создайте в корне директории с сайтом папку _layouts. Именно в ней по умолчанию Jekyll ищет шаблоны для страниц сайта.
1.2. Создайте в этой папке файл api_layout.html со следующим содержимым:
` page`.`title `
` content `
1.3. В файле index.md (его мы создали в прошлый раз и «отвязали» от шаблона по умолчанию), в frontmatter укажите, что для этой страницы будет использоваться шаблон api_layout.html:
---
layout: api_layout
---
2. Добавление спецификации, из которой будет собираться справочник
Чтобы добавить спецификацию, сделайте следующее:
2.1. Создайте в корне репозитория с сайтом папку _data. Это папка, которая предназначенная для хранения структурированных данных в форматах YAML, JSON или CSV. Очень удобно, чтобы разделить контент, который нам нужно рендерить, от шаблонов, скриптов и пр.
2.2. В папке _data создайте файл openapi_spec.yaml.
2.3. В файл openapi_spec.yaml поместите спецификацию (эту спецификацию мы с вами разработали на Курсе по проектированию и документированию API). Скопировать ее можно здесь.
3. Вывод содержимого спецификации на сайт
Чтобы вывести спецификацию на сайт, сделайте следюущее:
3.1. Создайте в корне репозитория с сайтом папку _includes. В Jekyll эта папка используется для хранения переиспользуемых фрагментов кода.
3.2. В папке _includes создайте файл api_reference.liquid. Его как раз мы и будем потом переиспользовать. Здесь будет находиться скрипт для вывода содержимого спецификации на страницу с необходимыми преобразованиями. Подробнее про Liquid — в документации.
3.3. В файл api_reference.liquid добавьте код для вывода содержимого спецификации openapi_spec.yaml на страницу сайта:
{% assign spec = site.data.openapi_spec %}
` spec `
3.4. В файл index.md добавьте код, который как раз и будет переиспользовать наш шаблон api_reference.liquid:
{% include api_reference.liquid %}
При рендеринге страницы Jekyll дойдет до этого кода, увидит там include, пойдет в папку _include и выполнит liquid-скрипт в файле api_reference.liquid.
Готово, если вы все сделали правильно, содержимое спецификации появится на странице сайта (не забываем, что рендеринг запускается командой bundle exec jekyll serve).
Да, выглядит это пока некрасиво (но главное — что содержимое спецификации выводится на страницу). Но все еще впереди. Красоту будем наводить в следующих постах.
Свериться с результатом, который должен у вас появиться, можно в ветке iteration_2 репозитория, специально подготовленного под текущую серию постов.