От переводчика: Я собирался сделать собственную статью по Nuxt Content, но наткнулся на готовую статью, которая отлично раскрывает тему. Лучше у меня вряд ли получится, поэтому я решил перевести. Написал автору в твиттер и практически сразу получил согласие. Статья будет с моими дополнениями для лучшего понимания темы.
Модуль Content в Nuxt это headless CMS основанной на git файловой системе, которая предоставляет мощные функции для создания блогов, документации или просто добавления контента на обычный сайт. В этой статье мы разберем большинство преимуществ этого модуля и узнаем как создать блог с его помощью.
Видео обзор готового проекта:
Начало работы
Установка
Чтобы начать работу с модулем Content, нам сначала нужно установить модуль с помощью npm или yarn.
yarn add @nuxt/content
npm install @nuxt/content
Затем мы добавим его в сборку модулей в файле nuxt.config.
export default { modules: ['@nuxt/content']}
Если вы создаете новый проект с помощью create-nuxt-app, можете выбрать опцию добавить модуль Content, и он будет установлен.
Создаем страницу
Модуль Content читает файлы в нашем каталоге
content/.
mkdir content
Если вы создали свой проект с помощьюcreate-nuxt-app, каталогcontent/будет уже создан.
Давайте создадим директорию articles/, куда мы
сможем добавлять статьи для нашего блога.
mkdir content/articles
Модуль Content может анализировать markdown, csv, yaml, json, json5 или xml файлы. Давайте создадим нашу первую статью в markdown файле:
touch content/articles/my-first-blog-post.md
Теперь добавим заголовок и текст для нашего сообщения в блоге:
# My first blog postWelcome to my first blog post using content module
В markdown мы создаем заголовок<h1>с помощью значка#. Убедитесь, что вы оставили пробел между ним и заголовком вашего блога. Для получения дополнительной информации о записи в markdown стиле смотрите Руководство по основному синтаксису.
Отображение контента
Чтобы отобразить контент на странице, мы используем динамическую страницу, добавив к странице знак
подчеркивания (_). Создав компонент страницы с именем
_slug.vue внутри папки blog, мы можем
использовать переменную params.slug, предоставляемую
vue router, для получения имени каждой статьи.
touch pages/blog/_slug.vue
Затем используем asyncData в компоненте страницы
для получения содержимого статьи до того, как страница будет
отрисована. Мы можем получить доступ к контенту через context,
используя переменную $content. Поскольку мы хотим
получить динамическую страницу, нам также необходимо знать, какую
статью нужно получить с помощью params.slug, который
доступен нам через context.
<script> export default { async asyncData({ $content, params }) { // fetch our article here } }</script>
Внутри асинхронной функции asyncData мы создаем
переменную с именем article, которая принимает
контент, используя await, за которым следует
$content. Нужно передать в $content
параметры того, что мы хотим получить, в нашем случае это папка
articles и slag, который мы получаем из
params. По цепочке в конце добавляем метод fetch, который
возвращает нужную статью.
<script> export default { async asyncData({ $content, params }) { const article = await $content('articles', params.slug).fetch() return { article } } }</script>
Чтобы отобразить контент, используем компонент
<nuxt-content />, передав переменную в параметр
document. В этом примере мы заключили его в HTML тег
article, согласно правилам семантического синтаксиса, но вы можете
использовать div или другой тег HTML, если хотите.
<template> <article> <nuxt-content :document="article" /> </article></template>
Теперь мы можем запустить сервер разработки и перейти по маршруту http://localhost:3000/blog/my-first-blog-post. Мы должны увидеть контент из .md файла.
Введенные переменные по умолчанию
Модуль Content Nuxt дает нам доступ к введенным переменным, которые мы можем показать в нашем шаблоне. Давайте посмотрим на переменные по умолчанию, которые вводятся в документ:
- body: содержимое документа
- dir: директория
- extension: расширение файла (.md в этом примере)
- path: путь к файлу
- slug: имя файла
- toc: массив, содержащий оглавление
- createdAt: дата создания файла
- updatedAt: дата последнего изменения файла
Мы можем получить доступ ко всем этим переменным, используя
созданную ранее переменную article.
Article это объект, который содержит все эти
дополнительные введенные переменные, к которым у нас есть доступ.
Давайте проверим их, распечатав с помощью тега
<pre>.
<pre> {{ article }} </pre>
Теперь на нашей странице мы видим, что у нас есть объект с переменной, которая представляет собой пустой массив, и переменную содержимого(body), которая включает все наши теги h1 и p, а также некоторую другую информацию, которую мы рассмотрим позже. Если мы прокрутим вниз, вы увидите все остальные переменные, к которым есть доступ.
"dir": "/articles","path": "/articles/my-first-blog-post","extension": ".md","slug": "my-first-blog-post","createdAt": "2020-06-22T10:58:51.640Z","updatedAt": "2020-06-22T10:59:27.863Z"
Это означает, что мы можем получить доступ к этим свойствам,
используя нашу переменную article, добавив точку и имя свойства,
которую мы хотим использовать. Например,
article.updatedAt даст нам дату последнего обновления
поста.
<p>Post last updated: {{ article.updatedAt }}</p>
Как видите, дата не так уж и читабельна для людей. Мы можем отформатировать ее, создав метод, который принимает дату и возвращает новую дату с параметрами года, месяца и дня, отформатированными так, как мы хотим.
methods: { formatDate(date) { const options = { year: 'numeric', month: 'long', day: 'numeric' } return new Date(date).toLocaleDateString('en', options) } }
А затем в нашем шаблоне мы можем использовать метод
formatDate, принимающий дату, которую мы получаем из
контента, и возвращающий уже отформатированную дату.
<p>Article last updated: {{ formatDate(article.updatedAt) }}</p>
Пользовательские введенные переменные
Мы также можем добавить пользовательские введенные переменные, добавив блок YAML в наш md файл. Он должен находиться в верхней части файла, иметь допустимый формат YAML и находиться между двумя тройными пунктирными линиями. Это полезно для добавления переменных SEO, таких как заголовок, описание и изображение вашей статьи.
---title: My first Blog Postdescription: Learning how to use @nuxt/content to create a blogimg: first-blog-post.jpgalt: my first blog post---
Теперь у нас есть переменные title, description, img и alt, к которым у нас есть доступ из объекта article`.
<template> <article> <h1>{{ article.title }}</h1> <p>{{ article.description }}</p> <img :src="article.image" :alt="article.alt" /> <p>Article last updated: {{ formatDate(article.updatedAt) }}</p> <nuxt-content :document="article" /> </article></template>
Чтобы отрендерить изображения, включенные в YAML разделе файла, нам нужно либо поместить их в статическую папку, либо использовать синтаксис::src="require(`~/assets/images/${article.image}`)".
Изображения, включенные в содержимое статьи, всегда следует помещать в папку static, поскольку @nuxt/content не зависит от Webpack. Эта папка не пропускается через Webpack, в отличие от папки assets.
Стилизация markdown контента
Если мы посмотрим на код получившейся страницы, мы увидим, что все, что написано внутри нашего файла, заключено в div с классом nuxt-content. Это означает, что мы можем легко добавить стили ко всем нашим элементам из нашего markdown файла, заключив их в класс nuxt-content.
<style> .nuxt-content h2 { font-weight: bold; font-size: 28px; } .nuxt-content h3 { font-weight: bold; font-size: 22px; } .nuxt-content p { margin-bottom: 20px; }</style>
Чтобы использовать стили с ограниченной областью видимости с
классом nuxt-content, вам необходимо использовать deep селектор:
/deep/, ::v-deep или
>>>
Все остальные данные, которые поступают из YAML раздела, можно оформить как обычно: используя TailwindCSS или добавив в CSS в стиль тега.
Наши теги из md файла преобразуются в правильные теги, что
означает, что теперь у нас есть два заголовка, два тега
<h1>. Удалим один из md файла.
Добавление иконки к ссылке наших заголовков
Обратите внимание, что внутри тега <h2> есть
тег <a> с href, который содержит id
для ссылки на себя, и тег span внутри него с
icon и icon-link классы. Это полезно для
ссылки на этот раздел страницы. Ссылки в заголовках пусты и поэтому
скрыты, поэтому давайте добавим им стиль. Используя классы значков,
мы можем добавить svg-иконки в качестве фонового изображения для
нашего значка. Сначала вам нужно будет добавить сами иконки в папку
с ресурсами assets. В этом примере я добавила его в папку svg и
взяла иконки Steve Schoger's Hero Icons.
.icon.icon-link { background-image: url('~assets/svg/icon-hashtag.svg'); display: inline-block; width: 20px; height: 20px; background-size: 20px 20px;}
Добавляем оглавление
Сгенерированная переменная toc позволяет нам
добавить оглавление к нашему посту в блоге. Давайте добавим
заголовки к нашему сообщению в блоге.
## This is a headingThis is some more info## This is another headingThis is some more info
Теперь мы можем видеть эти новые заголовки внутри массива
toc с идентификатором, глубиной и текстом. Значение
глубины является значением тега заголовка, поэтому значение глубины
2 приравнено тегу <h2> и равно 2, значение 3
тегу<h3> и т. д.
## This is a headingThis is some more info### This is a sub headingThis is some more info### This is another sub headingThis is some more info## This is another headingThis is some more info
Поскольку у нас есть доступ к toc и тексту, мы
можем перебрать и отобразить их все, а в компоненте
<NuxtLink> сделать ссылку на якорь раздела, на
который мы хотим создать ссылку.
<nav> <ul> <li v-for="link of article.toc" :key="link.id"> <NuxtLink :to="`#${link.id}`">{{ link.text }}</NuxtLink> </li> </ul></nav>
Теперь ссылки ToC работают, и нажатие на любую из них приведет
нас к нужной части документа. Модуль Content автоматически
добавляет идентификатор и ссылку к каждому заголовку. Если мы
проверим один из заголовков из нашего .md файла в инструментах
разработки браузера, мы увидим, что у нашего тега
<h2> есть идентификатор. Это тот же
идентификатор, который находится в toc, который по
сути из него и берется для ссылки на правильный заголовок.
Мы можем улучшить верстку дальше, используя динамические классы для стилизации классов заголовков в зависимости от глубины заголовка, которую мы можем добавить в наш тег nuxt-link. Если ссылка имеет глубину 2, добавьте отступ по оси y, а если глубина равна 3, добавьте поле слева и отступ внизу. Здесь мы используем классы TailwindCSS, но, конечно же, можно использовать собственные имена и стили классов.
:class="{ 'py-2': link.depth === 2, 'ml-2 pb-2': link.depth === 3 }"
Использование HTML в .md файлах
Иногда нам может понадобиться добавить HTML в наши файлы c разметкой. Давайте добавим div с некоторыми классами, чтобы он имел синий цвет фона с белым текстом, небольшим отступом и нижним краем.
<div class="bg-blue-500 text-white p-4 mb-4"> This is HTML inside markdown that has a class of note</div>
Добавление Vue компонента
А также мы можем добавлять Vue компоненты в .md файлы. Это означает, что если мы множество раз используем такие компоненты, как информационное окно или окно предупреждения, мы можем создать его с нужными нам стилями и передать текст в слот.
Теперь мы можем добавлять компоненты в наше приложение, установив для свойства components значение true в нашем файле nuxt.config. (начиная с v2.13)
export default { components: true}
Автоматический импорт компонентов не будет работать для <nuxt-content>, если мы не зарегистрируем их глобально, добавив глобальную папку внутри папки компонентов.
mkdir components/global
А теперь можно создать наш компонент InfoBox внутри этой папки.
<template> <div class="bg-blue-500 text-white p-4 mb-4"> <p><slot name="info-box">default</slot></p> </div></template>
Теперь в нашей разметке эти компоненты будут доступны без необходимости их импорта.
<info-box> <template #info-box> This is a vue component inside markdown using slots </template></info-box>
Глобальные компоненты будут доступны для всего нашего
приложения, поэтому будьте осторожны при добавлении компонентов в
эту папку. Это работает иначе, чем добавление компонентов в папку
components, которые добавляются (наверное, имеется в виду
импортируются прим. пер.) только в том случае, если они
используются (начиная с Nuxt v2.13 компоненты в папке components
импортируются автоматически, достаточно написать в Nuxt конфиге:
components: true прим. пер.).
От переводчика: На этом первая часть статьи подошла к концу. Дебби познакомила нас с мощным инструментом от создателей Nuxt'а, который они, кстати, сами используют на своем сайте для документации фреймворка. В этом, в общем-то, основное его применение. Если вы думали, что наконец-то нашли простую CMS, на которой можно быстро шлепать проекты и отдавать заказчику, то это не так. Из-за git-подобной системы наполнения контента, проект должен всегда быть под контролем разработчиков. Она идеальна для документации инструментов разработки, и любого другого контента не требующего частого обновления. Если же контент должен динамически обновляться из-за действий пользователей, то тут без базы данных не обойтись.
В следующей части мы узнаем как стилизовать код в статьях, сортировать статьи по различным параметрам, работать с API Content и многое другое.
Продолжение следует...
