Как создать приложение для документации с помощью Gatsby и Cosmic JS

Документация?… Документация. Допустим на секунду, что вы хотите создать способ легко публиковать и читать документы, эээ… документацию. К концу этого чтения вы сможете сделать именно это, используя мощь Gatsby (генератор статического сайта) и Cosmic JS (простая в настройке и использовании система управления контентом). Возьми кофе, найди удобное кресло и давай построим что-нибудь классное.

TL:DR

Демонстрация приложения Gatsby Documentation
Ознакомьтесь с кодовой базой

1.0 — Введение

Что такое Гэтсби?

Gatsby — это простая в использовании платформа для создания статических файлов веб-сайтов. Он поставляется в комплекте со всевозможными новшествами, такими как React JS для создания веб-компонентов и GraphQL для обработки состояния нашего компонента без необходимости настраивать что-то вроде Redux для обработки внешних данных.

Как насчет Космический JS?

Cosmic JS будет заниматься нашей публикацией и хранением данных. Его легко настроить и внедрить для таких приложений, но он достаточно масштабируемый, чтобы справляться с более сложными проектами в больших командах. Мы будем использовать это для создания и хранения нашего содержимого документации. Это позволит нам сосредоточиться на том, как наши пользователи взаимодействуют с нашим приложением, и пусть Cosmic JS сделает всю тяжелую работу.

В том, что все?

Ну нет… мы собираемся преобразовать наши документы из разметки в html, так как это нравится веб-браузерам. Для этого мы собираемся использовать пакет под названием Вскрытиекоторый может выполнять синтаксический анализ и преобразование уценки в HTML и из него.

Любые требования?

Ах да, вам понадобится доступ к терминалу, учетная запись Cosmic JS с ведро и объект документациии недавняя (выше) версия Узел JS установлен на вашем компьютере, чтобы установить необходимое программное обеспечение, чтобы это приложение работало. Я собираюсь использовать пряжу для запуска моих скриптов сборки, но вы можете использовать npm, если хотите. Просто не забудьте выбрать один (npm или yarn) и придерживайтесь его, так как когда придет время развертывания, все может стать немного неудобным.

Давайте строить!!

1.1 — Настройка нашей среды разработки

Для начала нам нужно установить Gatsby и установить наши зависимости. Очень просто. Gatsby использует удобный интерфейс командной строки (CLI) для создания исходных файлов проекта. Сначала мы хотим установить CLI, установив его глобально с помощью npm:

$ npm install -g gatsby-cli

Это дает нам доступ к gatsby команда и позволяет нам инициализировать наш проект. Запустите следующий скрипт, чтобы создать новый каталог, заполненный шаблоном проекта:

$ gatsby new gatsby-docs

Подождите секунду, пока сценарий завершится, и вы заметите, что создан новый каталог с именем gatsby-docs. Посмотрим, что внутри, поменяв каталоги:

$ cd gatsby-docs

вы должны увидеть структуру каталогов, подобную этой:

.
├── node_modules
├── src
├── .gitignore
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── LICENSE
├── package-lock.json
├── package.json
└── README.md

Многое из этого покажется знакомым, если вы привыкли создавать приложения Node, но кое-что будет немного новым. Вы должны иметь возможность запустить сервер разработки, выполнив сценарий запуска:

$ yarn start

Через секунду вы должны увидеть сообщение об успехе, сообщающее, что все скомпилировано правильно и ваше приложение работает.

Теперь вы можете открыть свой браузер, указав на localhost:8000 и посмотрите скомпилированный вывод. Должно получиться что-то очень похожее на это:

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

$ yarn add cosmicjs showdown highlight.js dotenv node-sass gatsby-plugin-sass gatsby-source-graphql

Вау… Много недавно установленных пакетов, но каждый из них очень полезен, клянусь.

  • cosmicjs будет использоваться для добавления нового контента в наше приложение.

  • showdown — это анализатор текста, который я упомянул, который будет обрабатывать уценку и преобразование html.

  • highlight.js будет обрабатывать нашу подсветку синтаксиса внутри нашего преобразованного текста уценки.

  • dotenv — это пакет переменных среды, который гарантирует, что наши конфиденциальные токены и/или среда выполнения настроены из .env файл

  • node-sass и gatsby-plugin-sass пакеты позволят использовать .scss файлы для стилизации наших компонентов.

  • gatsby-source-graphql позволит нам использовать запросы GraphQL к внешним данным (например, использовать Cosmic JS GraphQL API)

Со всем этим бизнесом мы можем заглянуть в наш каталог и настроить исходный код Gatsby для правильной работы.

2.0 — Настройка Гэтсби

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

Первый файл, который мы хотим изучить, это gatsby-config.js. Этот файл используется для настройки плагинов высокого уровня, которые позволяют правильно связать любой исходный код, который мы пишем, при сборке наших статических файлов. Он также содержит немного метаданных, которые описывают наш сайт для пользователей и могут быть запрошены в наших компонентах React.

Здесь мы добавим наши недавно установленные плагины в конфигурацию по умолчанию, которую вы видите перед собой. Сначала нам просто нужно добавить gatsby-plugin-sass в список плагинов, что позволяет нам импортировать файлы sass и использовать sass для написания разумных спецификаций стиля для каждого компонента.

Далее мы добавим объект в конец нашего списка плагинов для gatsby-source-graphql который настроит нашу внешнюю конечную точку API GraphQL, чтобы мы могли получать данные из Cosmic JS. Вот как все должно выглядеть:

настройка гэтсби

Теперь мы готовы выполнять запросы GraphQL к Cosmic JS GraphQL API! Далее, давайте на секунду поговорим о Гэтсби и о том, как все рухнет.

2.1 Создание нашего приложения с Gatsby

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

Давайте теперь создадим исходный код. Наш сайт будет использовать только две «страницы», одна из которых будет служить домашней страницей для списка созданной нами документации, а другая — для просмотра фрагмента документации. Но для получения содержимого, которое мы собираемся отображать, мы будем использовать GraphQL, который мы недавно настроили. Нам нужно будет добавить некоторые переменные в наш gatsby-node.js файл, чтобы позволить нашим статическим файлам иметь необходимые параметры для выполнения вызовов API.

Создайте файл .env и добавьте свои переменные среды Cosmic JS.

В меню Cosmic JS Bucket > Basic Settings вы увидите поля для slug-сегмента и клавиши чтения и записи внизу. Скопируйте все эти три элемента и добавьте их в файл .env.

В корне вашего проекта введите в свой терминал:

$ touch .env

Теперь создайте три строки:

настройка наших переменных окружения

Мы будем использовать их с нашим пакетом dotenv, чтобы разрешить нашим файлам src доступ к этим переменным, когда это необходимо.

Открыть gatsby-node.js и добавить переменные конфигурации на страницы

Теперь мы собираемся использовать встроенный в Gatsby API-интерфейс узла, чтобы предоставить каждой странице нашего сайта доступ к только что созданной переменной среды. Сначала мы импортируем переменные из нашего .env файл с помощью dotenv, то мы явно установим каждую переменную в контексте нашей страницы. Ваш файл должен выглядеть так:

предоставление нашим страницам их контекста

Создание нашей первой страницы

Теперь мы собираемся создать нашу первую страницу, которая будет захватывать все объекты документации и отображать их в корне нашего сайта, на index.js. Сначала давайте создадим наш список, создав папку в каталоге компонентов с названием docs — /src/components/docs/ и в этой папке мы создадим файл с названием index.js.

Это будет наш модуль, который сначала отображается, когда мы визуализируем нашу страницу. после получение наших документов. Вот исходный код:

компонент со списком наших документов

Что тут происходит:

Эта страница в основном выполняет большой цикл по нашему docs и возвращает какой-то причудливый jsx. Мы сопоставляем массив документов и создаем ссылку от Гэтсби, содержащую заголовок, дату и некоторый контент, в котором используется описание части опубликованной документации.

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

Обновите домашнюю страницу с нашими новыми компонентами

Теперь мы можем открыть файл нашей домашней страницы по адресу /pages/index.js и импортируйте компоненты, которые мы только что создали, и добавьте их в наш возвращенный jsx.

Домашняя индексная страница Гэтсби

Теперь любой docs созданный на Cosmic JS, появится здесь на главной странице!

Обратите внимание на экспортированный запрос в нижней части файла. Он содержит две переменные строкового типа, которые будут присутствовать, потому что мы установили контекст object в нашей конфигурации gatsby-node.

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

Создание нашей страницы отображения документа

Вместо того, чтобы добавлять новый файл в каталог pages в Gatsby, мы собираемся создать templates и создайте страницу шаблона, которую мы можем настроить при сборке, чтобы каждый раз при создании документа можно было создавать новую страницу, когда мы получаем наши документы из Cosmic JS.

Начните с создания templates каталог в корне вашего проекта, а затем создайте docPage.js файл внутри.

. 
├── _templates 
|    ├── docPage.js

Теперь добавьте шаблон страницы с экспортированным запросом, который будет извлекать отдельный документ из Cosmic JS:

компонент docPage

С этим шаблоном ничего не произойдет, пока мы не скажем Gatsby, что ему нужно создать страницу по этому шаблону. Мы делаем это для того, чтобы у Gatsby была возможность получить нашу документацию из Cosmic JS до того, как он создаст страницу, используя необходимые параметры для каждого запроса GraphQL в нижней части страницы. docPage.js. В конце концов, мы используем статические файлы сайта.

Обновите Gatsby Node для создания шаблонных страниц

Давайте продолжим и добавим функцию экспорта в gatsby-node.js так что мы строим шаблон docPage из наших данных GraphQL:

добавление нашего API createPages в gatsby-node.js

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

3.0 Развертывание

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

Моя рекомендация — использовать сетевая и свяжите свой исходный код с GitHub или где бы вы ни хранили свой код. Оттуда вы можете активировать сборочные крючки, чтобы перестраивать свой сайт всякий раз, когда происходят определенные события. Cosmic JS позволит отправлять запросы на публикацию в конечной точке, когда объекты создаются, удаляются, редактируются и т. д. Таким образом, вы можете легко связать их вместе, чтобы произошло какое-то волшебство. Имейте в виду, если вы хотите разрешить пользователям создавать документы из вашего пользовательского интерфейса: вам нужно будет вручную запускать запрос POST, чтобы активировать сборочный хук всякий раз, когда документ успешно создается.

Во всяком случае, это все для меня, ребята! Удачного взлома.

Похожие записи

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *