Как генерировать страницы из Markdown в Gatsby
Development | Комментировать запись
Одной из ключевых особенностей популярного генератора статических сайтов Gatsby является его гибкая поддержка источников контента. Gatsby может генерировать статические страницы практически из любого источника данных: из систем управления контентом (CMS), API, баз данных или даже из локальной файловой системы.
Файлы Markdown часто используются в качестве источника данных для Gatsby. Markdown – это простой язык разметки, разработанный для удобочитаемости, что делает его идеальным для написания документаций, публикаций в блогах или на любых других веб-сайтах, где пользователь встречается в большим количеством текста.
В данном руководстве вы узнаете, как на основе Gatsby создать статический сайт, который собирается из локальных исходных файлов Markdown. В своей работе мы будем использовать плагин gatsby-source-filesystem для сбора файлов и gatsby-transformer-comment для преобразования их в HTML.
Требования
- Локальная копия Node.js (для запуска Gatsby и создания сайта). Процедура установки зависит от операционной системы: Mac OS, Ubuntu, CentOS, Debian. Конечно, вы всегда можете найти последнюю версию на официальном сайте Node.js.
- Базовое знакомство с JavaScript.
- Общее знакомство с React и JSX, а также с элементами HTML, если вы хотите настроить пользовательский интерфейс (UI) для публикаций (это выходит за рамки данного руководства).
- Новый проект Gatsby по имени markdown-tutorial, созданный на основе gatsby-starter-default. Чтобы создать новый проект Gatsby с нуля, вы можете обратиться к разделу 1 руководства Как создать первый сайт на Gatsby.
Это руководство было протестировано на версиях Node.js v14.16.1, npm v6.14.12, Gatsby v3.10.2, gatsby-source-filesystem v3.10.0 и gatsby-transformer-comment v4.7.0.
1: Стандартизация контента Markdown
Учитывая гибкость Markdown как языка разметки, документы, написанные на Markdown, могут принимать различные формы и иметь самые разные уровни сложности. Gatsby не требует, чтобы вы форматировали все ваши файлы Markdown одинаково, но мы стандартизируем написание и хранение этих файлов, чтобы упростить организацию сайта и URL-адресов.
В этом руководстве мы будем добавлять публикации в блог. Каждая такая публикация должна иметь заголовок, удобный URL-адрес, дату и тело сообщения. Для начала мы создадим одну публикацию и назовем ее Learning About Gatsby: в ней мы сможем поделиться своим опытом изучения Gatsby со своими читателями.
Для хранения этой и будущих публикаций создайте в src новый каталог и назовите его blog. Если вы предпочитаете работать через командную строку, вы можете сделать это с помощью mkdir из корневого каталога проекта:
mkdir src/blog
Затем в этом новом каталоге создайте пустой файл Markdown. В этом руководстве имена файлов не контролируют опубликованный URL-адрес или SEO, поэтому приведенные здесь соглашения об именах нужны только для поддержания порядка. Присвойте вашему новому сообщению имя learning-about-gatsby.md.
Вы можете сделать это в своей среде IDE или использовать терминал с помощью touch:
touch src/blog/learning-about-gatsby.md
Теперь же мы можем создать фактическое содержание публикации. Откройте новый файл в редакторе и добавьте следующее:
--- title: "Learning about Gatsby" slug: "/blog/learning-about-gatsby" date: "2021-08-01" --- ## What I'm Working On Right now, I'm working through a [tutorial](https://www.8host.com/blog/) on using [Gatsby](https://www.gatsbyjs.com/) with Markdown.
Верхняя часть файла, заключенная в —, называется frontmatter и состоит из пар ключ-значение. Она написана на YAML (это язык конфигурации, отличный от Markdown). Ключи свойств идут слева, а значения – справа. В блоке frontmatter мы определили значения для заголовка, даты публикации и слага. Слаг – это настраиваемая часть URL-адреса страницы, которая идет после вашего доменного имени.
Любой текст, идущий после блока frontmatter, считается телом сообщения. В этой области мы поместили заголовок What I’m Working On, поставив два диеза (##) в начале строки. В Markdown это создает заголовок второго уровня, который Gatsby преобразует в теги <h2> </h2> в HTML. Под этим заголовком идет текст, который содержит ссылки, записанные синтаксисом Markdown:
[link_text](link_destination)
Сохраните изменения в learning-about-gatsby.md, а затем закройте файл.
Мы только что создали свой первый пост с помощью Markdown и сохранили его в исходном коде проекта. Также мы стандартизировали формат, включив конкретные значения свойств в frontmatter. Это позволит нам упорядочить исходный код и сыграет важную роль на последующих этапах. А следующий наш шаг – установить и настроить плагины, необходимые Gatsby для обработки новой публикации Markdown.
2: Установка и настройка плагинов
Создав файл Markdown, мы должны сообщить Gatsby, где их найти и как обработать. В этом разделе мы установим необходимые для этого плагины и обновим конфигурацию Gatsby, чтобы загрузить их.
Для обработки Markdown в Gatsby требуются два плагина: gatsby-transformer-remark и gatsby-source-filesystem. Первый плагин проанализирует Markdown и преобразует frontmatter в поля, которые сможет запрашивать Gatsby; второй плагин позволит нам переносить данные из локальной файловой системы в приложение.
Установим оба плагина одновременно, выполнив следующую команду в каталоге проекта Gatsby:
npm install gatsby-source-filesystem gatsby-transformer-remark
После установки плагинов откройте главный конфигурационный файл Gatsby, который находится в корневом каталоге проекта: gatsby-config.js. Редактируя этот файл, мы сообщим Gatsby, как использовать недавно установленные плагины для чтения файлов Markdown и начала их обработки. Добавьте следующий код в свои конфигурации:
module.exports = {
...
plugins: [
`gatsby-plugin-react-helmet`,
`gatsby-plugin-image`,
{
resolve: `gatsby-source-filesystem`,
options: {
name: `images`,
path: `${__dirname}/src/images`,
},
},
{
resolve: `gatsby-source-filesystem`,
options: {
name: `blog`,
path: `${__dirname}/src/blog`,
},
},
`gatsby-transformer-remark`,
`gatsby-transformer-sharp`,
...
Первый блок загружает плагин gatsby-source-filesystem и передает ему объект options, благодаря которому Gatsby сможет просканировать каталог src/blog в поиске файлов и использовать blog в качестве метки для коллекции. Последняя строка загружает плагин gatsby-transformer-comment со всеми стандартными параметрами (настраивать этот плагин в этом мануале мы не будем).
Читайте также: Объекты в JavaScript
Итак, Gatsby настроен для загрузки двух плагинов, необходимых для сканирования и анализа файлов Markdown. На следующем этапе мы создадим шаблон страницы Gatsby, чтобы позже объединить его с контентом Markdown и отобразить как веб-страницу.
3: Создание шаблона страницы Gatsby
Теперь Gatsby сможет просканировать файлы Markdown и обработает их с помощью gatsby-transformer-comment, но он по-прежнему не знает, как отображать их в браузере. В этом разделе мы расскажем, как дать ему эти инструкции при помощи шаблона страницы (также этот файл называется компонентом шаблона страницы).
Сначала в src/pages создайте пустой файл по имени {MarkdownRemark.frontmatter__slug}.js. Имя этого файла должно быть именно таким, потому что он использует API Gatsby (File System Route API), в котором имена файлов определяют маршруты (URL-адреса) на вашем сайте.
Примечание: File System Route API – довольно новая функция в Gatsby, потому сегодня все еще существуют руководства по Markdown, которые предлагают использовать createPages API в gatsby-node.js. Этот API не является устаревшим, однако он не нужен для реализации подхода, описанного в этом руководстве. Но если у вас есть проект, подразумевающий создание произвольных страниц, которые не отражают файловую систему (или каким-либо другим образом превышают возможности File System Route API), вам все равно может потребоваться createPages.
Чтобы создать свой компонент, добавьте в файл следующий код:
import { graphql } from "gatsby";
import * as React from "react";
import Layout from "../components/layout";
import Seo from "../components/seo";
export default function BlogPostTemplate({ data: { markdownRemark } }) {
const { frontmatter, html } = markdownRemark;
return (
<Layout>
<Seo title={frontmatter.title} />
<h1>{frontmatter.title}</h1>
<h2>{frontmatter.date}</h2>
<div className="post-body" dangerouslySetInnerHTML={{ __html: html }} />
</Layout>
);
}
export const pageQuery = graphql`
query ($id: String!) {
markdownRemark(id: { eq: $id }) {
html
frontmatter {
date(formatString: "MMMM DD, YYYY")
title
}
}
}
`;
Этот код состоит из двух разделов. В конце файла находится pageQuery, который использует тег GraphQL для оценки следующего за ним запроса GraphQL. Результаты этого запроса передаются в функцию BlogPostTemplate и предоставляют вам доступ к свойствам публикации, полученной через GraphQL.
Функция BlogPostTemplate – это компонент React, который возвращает JSX. В BlogPostTemplate мы показываем значения стандартных полей из frontmatter каждой публикации, заголовок и дату в элементах заголовка. Фактическое тело публикации мы поместили в <div> через класс post-body, используя React-свойство dangerouslySetInnerHTML для прямого вывода HTML-кода в визуализированный результат.
Нам необходимо использовать export default перед объявлением функции BlogPostTemplate, потому что Gatsby ожидает, что экспорт каждого файла шаблона страницы будет компонентом React, ответственным за создание окончательной отрисованной страницы.
Теперь, когда мы добавили код шаблона в файл, сохраним изменения и закроем его.
Итак, мы добавили новый файл шаблона страницы в проект Gatsby. Учитывая имя файла, которое использует File System Route API, он динамически создаст маршруты и страницы на основе результатов GraphQL и исходных файлов Markdown. Это был последний подготовительный шаг. В следующем разделе вы увидите, как Gatsby собирает эти страницы.
4: Предварительный просмотр контента и добавление новых публикаций
Мы написали весь код для преобразования файлов Markdown в веб-страницы и теперь можем предварительно просмотреть свою работу и добавить на свой сайт больше контента.
Чтобы предварительно просмотреть свои новые публикации в блоге и оценить всю проделанную вами работу, запустите эту команду в каталоге своего проекта:
npm run develop
Когда Gatsby будет готов, он предложит вам открыть проект в веб-браузере, что вы можете сделать, перейдя по адресу localhost:8000. Однако сначала на экране будет показана только домашняя страница приложения Gatsby, а не собранная из Markdown публикация. Чтобы увидеть свою новую запись в блоге, перейдите по адресу localhost:8000/blog/learning-about-gatsby/. По этой ссылке вы найдете свой файл Markdown в формате HTML.
С этого момента вы можете добавлять в блог новые публикации, создавая файлы Markdown в каталоге src/blog. Каждый раз, когда вы создаете новый пост, не забывайте следовать соглашениям, которые мы установили в frontmatter: в начале значения slug нужно указать /blog/, а после – желаемый путь, также нужно указать заголовок и дату для публикации.
Чтобы попробовать сделать это, скопируйте файл learning-about-gatsby.md в качестве основы для новой публикации по имени continue-learning.md:
cp src/blog/learning-about-gatsby.md src/blog/continuing-learning.md
Затем откройте новый файл и внесите следующие изменения в его содержимое (они выделены красным):
--- title: "Continuing to Learn" slug: "/blog/continuing-learning" date: "2021-08-01" --- ## Update I'm continuing to learn Gatsby to build some fast static sites!
В этом файле мы сохранили прежнее форматирование, но изменили title, slug и содержание публикации в блоге. Сохраните файл и выйдите из него.
После того как сервер восстановит ваш сайт Gatsby, перейдите по адресу http://localhost:8000/blog/continuing-learning в браузере. Вы найдете свою новую публикацию.
Примечание: Если вы хотите добавить через Markdown страницы вне блога, измените значение slug на любой другой необходимый путь. При этом обязательно используйте новые папки, чтобы ваши файлы хранились в порядке.
Теперь на вашем сайте Gatsby есть новые страницы, созданные с помощью Markdown.
Заключение
Выполнив шаги, описанные в этом руководстве, вы добавили в свой проект Gatsby файлы Markdown, настроили Gatsby для поиска этих файлов и их обработки, а также создали шаблон для отображения публикаций как новых страниц. Некоторые из описанных выше шагов можно пропустить, используя этот шаблон Gatsby для Markdown, однако вручную вы можете настроить сайт Gatsby с поддержкой Markdown именно так, как вы этого хотите.
Ссылаться на любую новую публикацию или страницу можно с помощью компонента Link. Но если на вашем сайте используется большое количество файлов Markdown, которые быстро меняются, вы можете добавить динамический список, чтобы посетители вашего сайта могли быстро находить самые последние публикации. При этом вы можете использовать тег GraphQL для запроса публикаций Markdown, которые вы хотите собрать в список, а затем выполнить итерацию и отобразить их в виде ссылок. Узнать больше об этом можно в этом руководстве.
Tags: Gatsby, HTML, markdown