Документация? … Документация. Допустим, на секунду вы хотите создать способ легко публиковать и читать документы, ошибки … Документация. К концу этого прочитана вы сможете сделать только что, все с силой GATSBY (статический генератор сайта) и Cosmic JS (простой в настройке и использовании системы управления контентом). Возьмите кофе, найдите удобное кресло и давайте построим что-то круто.
TL: доктор
PATSBY Документация Приложение Demo Проверьте кодовую базу
1.0 – Введение
Что такое GATSBY ?
GATSBY – это простое в использовании Framework для создания статических файлов веб-сайта. Он поставляется в комплекте со всеми видами горяковидства, таких как React JS для создания веб-компонентов, и GraphQL для обработки нашего компонента компонентов без необходимости настроить что-то вроде Redux для обработки внешних данных.
Как насчет Космические JS ?
Космические JS будут обрабатывать наше публикацию и хранение данных. Легко настроено и легко реализовать для таких приложений, так и достаточно масштабируемым, чтобы справиться с более сложными проектами в более крупных командах. Мы будем использовать это для создания и хранения нашей документации. Это позволит нам сосредоточиться на том, как наши пользователи взаимодействуют с нашим приложением, и пусть Cosmic JS делает всю тяжелую подъем.
Это все?
Ну нет … Мы собираемся преобразовать наши документы от Markdown до HTML, поскольку это какие веб-браузеры. Для этого мы собираемся использовать пакет под названием Showdown , который может обрабатывать разбор и преобразование уценки до HTML и из HTML.
Любые требования?
О да, вам нужно будет получить доступ к терминалу, аккаунт Cosmic JS с Ведро и объект документации и недавняя (ish) версия Узел js Установлено на вашем компьютере, чтобы установить необходимое программное обеспечение, чтобы сделать это приложение. Я собираюсь использовать пряжу, чтобы запустить сценарии сборки, но вы можете НПМ, если хотите. Просто не забудьте выбрать одну (NPM или пряжу) и придерживайтесь его, так как все может получить немного волосаты, когда пришло время развернуть.
Давайте построим !!
1.1 – Настройка нашей среды развития
Чтобы начать, мы захочем установить GATSBY и установить наши зависимости. Очень просто. GATSBY использует удобный интерфейс командной строки (CLI) для создания наших исходных файлов проекта. Сначала мы захочем установить CLI, установив его глобально с NPM:
$ npm установить -g gatsby-cli
Это дает нам доступ к GATSBY Команда и позволяет нам инициализировать наш проект. Запустите следующий скрипт, чтобы создать новый каталог, заполненный шаблоном проекта:
$ GATSBY новые 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
Большая часть этого будет выглядеть знакомы, если привыкли создавать приложения узла, но некоторые из этого будут немного новыми. Вы должны быть в состоянии получить сервер разработки и запуститься, выполняя сценарий запуска:
Запуск пряжи
Через секунду вы должны увидеть подсказку успеха, позволяю вам знать, что все скомпилировано правильно, и ваше приложение живут.
Теперь вы можете открыть свой браузер, указывающий на localhost: 8000 и увидеть скомпилированный выход. Это должно выглядеть что-то очень похожее на это:
Поздравляю! Вы настроили рабочий сайт GATSBY. Но прежде чем мы копаем, что происходит под крышками, давайте установим остальные наши зависимости, которые будут включать наше приложение:
$ пряжа Добавить Cosmicjs Showdown Highlight.js dotenv узел-сасс gatsby-plugin-sass gatsby-source-graphql
WHOA … Это много недавно установленных пакетов, но каждый из них очень полезной, я клянусь.
Cosmicjsбудет использоваться для добавления нового контента в наше приложение.ShowdownЯвляется ли текстовый парсер, который я упомянул, что будет обрабатывать разметки и преобразование HTML.highlight.jsСобирается обрабатывать наш синтаксис подсветки внутри нашей преобразованной текста разметки.ДоценвЭто пакет переменной среды, который удостоверится, что наши чувствительные токены и/или среда выполнения настроен из A.envфайлУзел-сассиGATSBY-Plugin-SassПакеты позволят использовать.scssФайлы для стиля наших компонентов.GATSBY-Source-GraphQLпозволит нам использовать запросы GraphQL на внешние данные (то есть – используйте API Cosmic JS GraphQL)
Со всем этим бизнесом вы можете посмотреть наш каталог и настроить наш исходный код GATSBY для правильной работы.
2.0 – Настройка GATSBY
Теперь мы можем перекопать в нашем каталоге и убедиться, что GATSBY настроен правильно для использования технологий, которые будут масштабируемо и разумно включать в себя наше приложение.
Первый файл, который мы захочем посмотреть на gatsby-config.js Отказ Этот файл используется для настройки высокоуровневых плагинов, которые позволяют любой исходный код, который мы пишем, чтобы быть правильно в комплекте, когда наши статические файлы будут созданы. Он также содержит немного метаданных, которые описывают наш сайт сайта для пользователей и могут быть запрошены в наших компонентах реагирования.
Здесь мы добавим наши недавно установленные плагины в конфигурацию по умолчанию, которую вы видите перед вами. Сначала нам просто нужно добавить GATSBY-Plugin-Sass В список плагинов, позволяющий им импортировать файлы SASS и используйте SASC, чтобы написать разумные характеристики для стилей для каждого компонента.
Далее мы добавим объект к концу нашего списка плагинов для GATSBY-Source-GraphQL Это настроит нашу внешнюю конечную точку GraphQL API, чтобы позволить нам получать данные из Cosmic JS. Вот как все должно выглядеть:
Настройка GATSBY
Теперь мы можем сделать запросы GraphQL к API Cosmic JS GraphQl! Далее давайте поговорим на секунду о GATSBY и как все будет сломать.
2.1 Создание нашего приложения с GATSBY
Я упомянул, что GATSBY – это статический генератор сайта, но что это значит? GATSBY берет весь модный код, который мы создаем и создают статические файлы, которые предварительно настроены с использованием файлов конфигурации, которые мы указываем. При этом мы получаем повышенную производительность для сайтов, которые могут иметь много изображений, данные для получения данных и другие активы, которые могут замедлить веб-приложения.
Давайте теперь получим какой-то исходный код. Наш сайт собирается использовать только две «страницы», которые будут служить домашней странице, чтобы перечислить документацию, которую мы создали, и одна для просмотра куска документации. Но чтобы получить содержание, которое мы собираемся отображать, мы собираемся использовать GraphQL, который мы недавно настроили. Нам нужно будет добавить некоторые переменные на наше gatsby-node.js Файл Чтобы разрешить нашим статическим файлам иметь необходимые параметры для создания вызовов API.
Создайте файл .env и добавьте вашу космические переменные среды JS
В вашем ведре COSMIC JS> Основные настройки меню «Настройки» вы увидите поля для ковшовых и прочитанных и записывающих клавиш вниз внизу. Скопируйте все три из этих вещей и добавьте их в файл .env.
В вашем корне проекта введите в свой терминал:
$ touch .env.
Теперь создайте три строки:
Настройка нашей среды переменные
Мы будем использовать их с нашим пакетом dotenv, чтобы позволить нашим файлам SRC доступ к этим переменным при необходимости.
Открыть GATSBY-NODE.JS. и добавьте переменные конфигурации на страницы
Теперь мы собираемся использовать GATSBY встроенный узел API узел, чтобы дать каждую страницу на нашем доступе к сайту к переменной среды, которую мы только что создали. Сначала мы импортируем переменные из наших .env Файл с помощью dotenv, то мы явно установим каждую переменную в контексте нашей страницы. Ваш файл должен выглядеть так:
давая нашим страницам их контекст
Создание нашей первой страницы
Теперь мы собираемся создать нашу первую страницу, которая будет схватить все объекты документации и отображать их в корне нашего сайта, на index.js Отказ Сначала давайте создадим наш список, создав папку в каталоге компонентов под названием Docs – /src/Компоненты/Документы/ И в этой папке мы создадим файл с названием index.js Отказ
Это будет наш модуль, который впервые отображается, когда мы оказываем нашу страницу после поднимая наши документы. Вот исходный код:
Компонент, списка наших документов
Что тут происходит:
Эта страница в основном управляет большой петлей на нашем Документы и возвращает некоторые модные JSX. Мы проводим через массив документов и производите ссылку из GATSBY, которая содержит заголовок, дату и некоторое содержание, которое использует описание для публикации документации, которая была опубликована.
Не стесняйтесь добавлять любой .scss Файлы к этому каталогу, чтобы получить стиль, который работает для вас для данных названий классов.
Обновите страницу «Главная» с нашими новыми компонентами
Теперь мы можем открыть наш домашний файл страницы в /pages/index.js И импортируйте компоненты, которые мы только что создали и добавили их в наш возвращенный JSX.
Главная страница HATSBY
Теперь любой Документы Создано на Cosmic JS, появится здесь на домашней странице!
Обратите внимание на экспортированный запрос в нижней части файла. Он содержит два переменной типа строки, которая будет присутствовать, потому что мы устанавливаем контекст Объект в нашей конфигурации узла GATSBY.
С нашей недавно созданной домашней страницей, давайте создадим наш представление DOC, который будет отображать содержимое от документации, которую мы публикуем.
Создание нашей док-дисплея
Вместо добавления нового файла в каталог страниц в GATSBY мы собираемся создать Шаблоны Справочник и сделайте страницу шаблона, которую мы можем настроить в сборке, чтобы каждый раз, когда док создан, новая страница может быть создана при получении наших документов из Cosmic JS.
Начните с создания Шаблоны каталог в вашем корневом проекте, а затем создание docpage.js файл внутри.
. ├── _templates | ├── docPage.js
Теперь добавьте шаблон страницы в комплекте с экспортированным запросом, который будет получать единственный документ от Cosmic JS:
Компонент Docpage
Ничто не произойдет с этим шаблоном, пока не скажу GATSBY, что ему нужно создать страницу, используя этот шаблон. Мы делаем это, так что у GATSBY есть возможность извлечь нашу документацию от Cosmic JS до того, как она строит страницу, используя необходимые параметры для каждого запроса GraphQL в нижней части docpage.js Отказ Мы используем статические файлы сайта в конце концов.
Обновите узел GATSBY для создания страниц шаблонов
Давайте пойдем вперед и добавьте функцию экспорта на gatsby-node.js так что мы строим шаблон docpage из наших данных graphql:
Добавление наших Createpages API в GATSBY-Node.js
Теперь, когда GATSBY создает свои страницы, то есть – страница индекса приведет к нашим документам и создает страницу для каждого доктора, которая извлекается и прикрепляет все необходимые параметры к содержимому содержимого каждой страницы. Таким образом, наш компонент шаблона отображается, и наш запрос GraphQL должен добиться успеха!
3.0 Развертывание
Наконец, мы можем говорить о развертывании и о том, как работают статические сайты. Развертывание этого плохого мальчика может быть немного сложно, так как этот сайт использует статическую сборку, которая не будет иметь необходимых страниц вновь созданных документов до тех пор, пока служба развертывания не будет возможности перестроить.
Моя рекомендация – использовать NetLify и свяжите свой источник из Github или где бы вы ни хранили свой код. Оттуда вы можете вызвать BuildHooks, чтобы восстановить свой сайт всякий раз, когда случаются определенные события. COSMIC JS позволит вам выпустить почтовый запрос на конечную точку, когда объекты создаются, удалены, отредактированы и т. Д., Итак, вы можете легко связать два вместе, чтобы сделать некоторую магию. Имейте в виду, если вы хотите позволить пользователям создавать документы в рамках вашего пользовательского интерфейса: вам нужно будет уйти от увольнения пост-запроса вручную, чтобы активировать BuildHook, когда док успешно создан.
Во всяком случае, это все для меня, ребята! Счастливый взлом.