Как использовать сторонние темы в Gatsby

Development | Amber | Комментировать запись

Gatsby 1.0 вышел в 2017 году и с тех пор продолжает выпускать новые функции, сохраняя при этом высокую гибкость настройки генератора статических сайтов. Дополнительные функции Gatsby представлены в виде плагинов, новых API, утилит и параметров конфигурации. Каждую из этих функций можно использовать как по отдельности, так и комбинировать с другими для конкретных случаев использования. Поскольку универсальные комбинации функций и настроек для разных сайтов все же существуют, Gatsby представил темы.

Темы в Gatsby – это конкретные плагины, которые действуют как наборы параметров конфигурации, функций и/или элементов пользовательского интерфейса (UI). Разделение общих функций на поддерживаемые темы упрощает обслуживание сайта в актуальном состоянии, а также позволяет вам тратить меньше времени на настройку сайта и больше – на разработку контента.

В этом мануале вы узнаете, как установить, настроить и использовать тему Gatsby для публикации сообщений в блоге: gatsby-theme-blog. Этот плагин объединяет в одном удобном пакете несколько функций, среди которых поддержка многомерных выражений и подсветка кода. Здесь мы продемонстрируем использование тем Gatsby на примере gatsby-theme-blog, а описанный тут процесс в дальнейшем вы сможете применить к другим темам.

Требования

• Локальная установка Node.js для запуска Gatsby и создания вашего сайта. Процедура установки зависит от операционной системы. Следуйте инструкциям для вашего дистрибутива: Mac OS, Ubuntu, CentOS, Debian.
• Базовое знакомство с JavaScript для работы в Gatsby.
• Новый проект Gatsby, созданный на gatsby-starter-default. Чтобы создать новый проект Gatsby с нуля, вы можете обратиться к разделу 1 руководства Как создать первый сайт на Gatsby.

Это руководство было протестировано на версиях Node.js v14.16.1, npm v6.14.12, Gatsby v3.11.1 и gatsby-theme-blog v3.0.0.

1: Поиск и установка темы

Несмотря на то, что данный мануал сосредоточен на конкретной теме gatsby-theme-blog, каждый описанный здесь шаг применим ко всем темам Gatsby в целом.

Итак, первым шагом будет найти тему, которую вы хотите использовать, и установить ее с помощью npm.

Gatsby предоставляет авторам плагинов и тем рекомендации о том, как им следует публиковать свои пакеты Gatsby, что упрощает поиск темы, соответствующей вашим потребностям. Разработчики тем должны помечать свои пакеты ключевыми словами gatsby и gatsby-theme, которые затем сканируются реестрами пакетов (где фактически размещаются файлы), после чего файлы становятся доступными для поиска.

В этом мануале рассматривается пример создания сайта с блогом. Как правило, для таких сайтов разработчики ищут тему с поддержкой многомерных выражений, подсветкой кода и т.п. У Gatsby есть собственный браузер плагинов, однако на самом деле он извлекает свои списки из реестра npm, поэтому начинать поиск нужно непосредственно в поисковой системе реестра npm. Используя поисковый запрос blog keywords:gatsby-theme, вы ограничите результаты только теми плагинами, в имени которых есть ключевое слово gatsby-theme:

В этом руководстве мы будем работать с gatsby-theme-blog, поэтому выберите этот пакет. Выбрав gatsby-theme-blog в качестве темы, которую вы собираетесь установить, вы должны установить ее вместе с ее зависимостями. Перейдите к вашему проекту Gatsby и выполните следующую команду в каталоге:

npm install gatsby-theme-blog

После установки зависимостей вы получите сообщение:

...
+ gatsby-theme-blog@3.0.0
added 262 packages from 181 contributors and audited 2391 packages in 49.706s

Теперь, когда вы установили тему и ее зависимости в свой проект, пришло время перейти к загрузке и настройке темы в проекте Gatsby.

2: Загрузка и настройка темы

Итак, тема установлена, и сейчас вы можете начать использовать ее на своем сайте и изменить ее в соответствии со своими потребностями. Основная инициализация и настройка тем в Gatsby выполняется путем редактирования корневого конфигурационного файла gatsby-config.js. На этом этапе мы отредактируем конфигурационный файл, чтобы загрузить в свою тему нужные параметры.

Откройте файл gatsby-config.js в любом удобном редакторе и добавьте следующее:

module.exports = {
  plugins: [
    ...
    `gatsby-plugin-image`,
    {
      resolve: 'gatsby-theme-blog',
      options: {
        basePath: '/posts',
        contentPath: `md/posts`,
      }
    },
    `gatsby-transformer-sharp`,
    ...
  ]
}

В этом коде есть два важных параметра, для которых применяются пользовательские значения. Тема использует параметр basePath для установки URL-адреса блога, а contentPath сообщает теме, где найти файлы Markdown для публикации сообщений в блоге. Значение md/posts в contentPath определяет каталог, в котором будут находиться файлы Markdown.

После добавления этого кода сохраните конфигурационный файл.

Тема gatsby-theme-blog предлагает дополнительные настройки, описанные в файле README.

Примечание: Каждая тема Gatsby имеет свои особенности, потому очень важно обращаться к документации выбранной вами темы и точно следовать ее указаниям.

Итак, вы настроили тему через ее файл конфигурации Gatsby. Следующим нашим шагом будет изучение и тестирование новых функций, которые тема добавляет на ваш сайт.

3: Тестирование темы

Теперь, когда ваша тема установлена, настроена и загружена, вы можете внедрить ее на свой сайт. В этом разделе рассказывается, как протестировать некоторые новые функции, связанные с темой, и просмотреть результаты.

Мы протестируем поддержку MDX, подсветки кода и обработки Markdown при помощи нового файла, который содержит сообщение для блога. Во-первых, вам нужно будет создать каталог для хранения файлов, который должен отвечать настройке contentPath (из раздела 2). Вы можете создать этот каталог либо вручную в своем файловом браузере, либо терминале, выполнив эту команду в корневом каталоге проекта Gatsby:

mkdir -p ./md/posts

Затем создайте пустой файл MDX, my-first-post.mdx, который будет содержать контент для новой публикации. Опять же, создать его можно вручную или в терминале:

touch ./md/posts/my-first-post.mdx

Откройте пустой MDX-файл и поместите в него такие строки:

---
title: Learning Gatsby Themes and Trying MDX
slug: /posts/gatsby-theme-learning
date: 2021-08-16
excerpt: A post about learning Gatsby themes and trying out some MDX.
---

## Welcome!

This is a post where I plan to share my journey learning Gatsby Themes, and to try out some MDX.

## Resources

<ul>
{[
                {
                               link: 'https://www.gatsbyjs.com/',
                               text: 'Gatsby Website',
                               note: 'Official Website for Gatsby'
                },
                {
                               link: 'https://www.gatsbyjs.com/docs/themes/',
                               text: 'Gatsby Theme Documentation',
                               note: 'Documentation for Gatsby Theme usage and development'
                },
                {
                               link: 'https://www.digitalocean.com/community/tutorial_series/how-to-create-static-web-sites-with-gatsby-js',
                               text: 'DigitalOcean - "How To Create Static Web Sites with Gatsby.js"',
                               note: 'A DigitalOcean tutorial series on using Gatsby JS'
                }
].map(item => (
                <li key={item.link}>
                               <a href={item.link} target="_blank">{item.text}</a>
                               <ul>
                                               <li>{item.note}</li>
                               </ul>
                </li>
))}
</ul>

## Code Sample

To try out code highlighting in this theme, here is a snippet of JavaScript code. This code won’t run in your browser; it is for visual use only.

В верхней части файла есть раздел, заключенный в —. Он представляет собой набор пар ключ-значение, называемых frontmatter. Не все темы используют одни и те же ключи; те, которые вы используете в своем посте, были тщательно отобраны из ключей, используемых темой gatsby-theme-blog. Мы определили собственный заголовок, слаг (URL-путь), дату публикации и выдержку (короткий текст для предварительного отображения на странице /posts).

Весь текст, который следует за заголовком, начиная с «Welcome!», будет основной частью сообщения. Два символа решетки (##) перед заголовком сообщают Markdown, что это заголовок уровня 2, который также используется для раздела «Resources».

В разделе «Resources» мы впервые видим то, что отличает MDX от обычного Markdown: синтаксис JSX React для встраивания компонентов React, которые объединяются с Markdown и отображаются на одной странице. В своем посте мы используем JSX, чтобы превратить коллекцию ресурсов Gatsby в список ссылок HTML.

Чтобы протестировать функцию подсветки синтаксиса кода, связанную с gatsby-theme-blog, добавьте блок Markdown кода Fenced Code Block в конец файла:

    ```js
    function saySomething(name) {
               console.log(`Hello ${name}!`);
               console.log(`Isn't learning about Gatsby fun?!`);
    }
    saySomething('Arthur');
    ```

При этом тройные обратные кавычки используются, чтобы указать границы того, где начинается и заканчивается код.

Сохраните и закройте файл MDX, когда закончите редактирование.

Чтобы просмотреть этот пост как читатель и протестировать все функции темы, выполните следующую команду:

npm run develop

Когда все будет готово, интерфейс командной строки Gatsby предложит вам открыть проект в веб-браузере, что вы можете сделать, перейдя по ссылке localhost:8000. Чтобы увидеть новую страницу со списком блогов, перейдите на localhost:8000/posts, а чтобы просмотреть эту конкретную новую публикацию, перейдите на localhost:8000/posts/gatsby-theme-learning/. Вы увидите свое сообщение на экране.

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

4: Что такое shadowing?

Итак, мы уже установили и настроили тему в Gatsby и выполнили конфигурацию в файле gatsby-config.js, изменив те параметры, которые позволяет менять автор темы. Однако если вам нужно изменить в теме то-то еще, кроме этих параметров, вы должны использовать так называемый shadowing.

Термин shadowing обозначает практику переопределения или расширения встроенного файла темы вашими собственными модификациями. Если вы знакомы с WordPress, это напомнит вам концепцию дочерней темы.

В Gatsby любой файл в исходном коде темы можно «затенить»: как методы, влияющие на ноды Gatsby и создание файлов, так и элементы пользовательского интерфейса и макеты. Давайте «затеним», скроем файл компонента React по имени bio-content.js, чтобы настроить отображение биографии под каждым сообщением. Скрывая этот единственный файл, вы повлияете на внешний вид каждой записи в блоге, которая проходит через плагин gatsby-theme-blog.

Первый шаг такого скрытия — создать в каталоге src папку с точно таким же именем, что и у плагина темы, который вы хотите «затенить». Это можно сделать вручную или с помощью терминала:

mkdir src/gatsby-theme-blog

Затем нужно создать одноименный файл в той же структуре каталогов для любого конкретного файла в теме, который вы хотите «затенить». Поскольку мы собираемся лишь немного изменить существующий компонент bio, мы сэкономим время, скопировав существующий файл с помощью команды cp:

mkdir -p src/gatsby-theme-blog/components
cp node_modules/gatsby-theme-blog/src/components/bio-content.js src/gatsby-theme-blog/components/bio-content.js

Теперь откройте новый файл и внесите в него такие поправки:

import React, { Fragment } from "react"

const BioContent = () => (
  <Fragment>
    <p>Content by DigitalOcean</p>
    <p>License Info:</p>
    <p
      style={{
        margin: "10px 20px",
        padding: 8,
        backgroundColor: "#0069ff",
        color: "white",
        borderRadius: 12,
      }}
    >
      This work is licensed under a Creative Commons
      Attribution-NonCommercial-ShareAlike 4.0 International License.
    </p>
  </Fragment>
)

export default BioContent

Сохраните и закройте этот файл, когда закончите редактирование.

В этом файле мы «затенили» исходный файл bio-content.js, заменив текст-заполнитель именем автора и информацией о лицензии. Для этого мы заменили JSX, возвращаемый компонентом BioContent. Код style={{}} — это пример встроенного CSS, который мы использовали для добавления цвета и пробелов в описании лицензии.

Снова запустив команду npm run development в своем терминале, вы запустите сервер разработки Gatsby и сможете просмотреть изменения во всех своих сообщениях в блоге.

Как видите, shadowing позволяет настраивать стороннюю тему Gatsby за пределами ее стандартной конфигурации, вносить свои собственные переопределения и расширения.

Итоги

Выполнив действия, описанные в этом руководстве, вы получили сайт Gatsby, использующий стороннюю тему, которая извлекает несколько компонентов и фрагментов связанных функций в виде единой зависимости. Благодаря этой упакованной функциональности ваш сайт теперь легче обновлять, и он может содержать гораздо меньше кода, несмотря на наличие дополнительных функций. Вы также узнали, как использовать shadowing для пользовательской настройки сторонних тем Gatsby.

Хотя это руководство использует конкретную стороннюю тему, изложенные в нем подходы и рекомендации применимы ко всем темам Gatsby в целом. Чтобы узнать больше о темах Gatsby, взгляните на официальную документацию проекта.