11.10.2020 14:16
js_n00b 2 2000 Источник

Создание блога на Nuxt Content


От переводчика: Я собирался сделать собственную статью по 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 post

Welcome 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 файла.


статья из файла 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 Post
description: Learning how to use @nuxt/content to create a blog
img: first-blog-post.jpg
alt: 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 heading

This is some more info

## This is another heading

This is some more info

Теперь мы можем видеть эти новые заголовки внутри массива toc с идентификатором, глубиной и текстом. Значение глубины является значением тега заголовка, поэтому значение глубины 2 приравнено тегу <h2> и равно 2, значение 3 тегу<h3> и т. д.


## This is a heading

This is some more info

### This is a sub heading

This is some more info

### This is another sub heading

This is some more info

## This is another heading

This 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 и многое другое.


Продолжение следует...