Опубликуйте сайт Vuepress на страницах GitHub с помощью Travis
published on August 3, 2018 vuepress version: 0.13.1
Vuepress - замечательный генератор статических сайтов, созданный Эваном Ю, создателем Vuejs. Философия Vuepress такая же, как и у Vuejs, и ее можно резюмировать одним словом: простота.
На данный момент Vuepress очень хорош для создания сайтов документации, и, как обычно в экосистеме Vuejs, документация - это единственное, что вам нужно для начала.
Поскольку мне нужно было выяснить, как соединить точки, чтобы использовать Трэвиса, я решил поделиться, чтобы ускорить процесс другого искателя приключений.
Vuepress создает статические веб-сайты, состоящие из простых HTML и js. Их можно развернуть на любом статическом хосте веб-сайта, дешевых взаимных серверах, а также на GitHub. Vue press - очень хороший вариант для совместной работы в команде для создания документации. Объединение его с git и GitHub упрощает совместную работу и отслеживание изменений. GitHub, связанный с Трэвисом, позволит команде не беспокоиться о том, как публиковать, а просто добавлять документацию, отправлять ее, а все остальное делается за них (нас).
Кроме того, GitHub может работать как (базовая) CMS для вашей документации, поскольку там можно создавать и редактировать файлы. Это может быть очень полезно для быстрого обновления или для менее технических пользователей, которые не хотят устанавливать git и установить редактор кода на свой компьютер.
Vuepress генерирует страницы и навигацию на основе содержимого файлов Markdown. Markdown легко изучить, и фактически все редакторы контента в компании, над которой я работаю, используют Markdown для публикации в Интернете. На их обучение и передачу и небольшую шпаргалку уходит около 15 минут.
Для этой настройки я предлагаю создать репозиторий для работы с документацией и репозиторий, в котором Трэвис будет автоматически публиковать сайт каждый раз, когда происходит нажатие на ветку `master`.
Для того, чтобы эта установка работала, вам понадобятся:
- Аккаунт Трэвис
- Аккаунт GitHub
- Рабочая установка Vuepress
Все остальные конфигурации являются необязательными и позволяют добавлять боковые панели, верхнюю навигацию, заголовок проекта и т. Д.
<publication-repo-name> - это путь после github.com/<username || organisation name>/. Он понадобится для работы страницы GitHub. Так что да ... Создайте два репозитория:
- Рабочий репозиторий
- Репозиторий публикаций
На вашем компьютере создайте папку, в которой будет размещен ваш проект, перейдите в нее и запустите проект git, мы создадим минимальный package.json файл, .travis.yml для хранения конфигурации Travis, папки .gitignore и docs, которые будут содержать нашу конфигурацию Vuepress и содержание. Затем свяжите его с вашим рабочим репозиторием, добавив правильный удаленный источник.
$ mkdir <folder name>
$ cd <folder name>
$ git init
$ touch package.json .travis.yml .gitignore
$ mkdir -p docs/.vuepress
$ cd docs/.vuepress
В результате структура папок выглядит так:
└── <folder name> ├── docs | └──.vuepress | └── config.js ├── .gitignore ├── .travis.yml ├── package.json └── README.md //optional
Vuepress прост в установке, и вся его конфигурация хранится в папке .vuepress. Единственная конфигурация, которая необходима для работы этого проекта, - это создать в корне этой папки config.js файл, который экспортирует модуль со следующим содержимым и любой дополнительной конфигурацией, которую вы хотите для своего проекта.
module.exports = {
base: ‘/<publication-repo-name>/’,
// ...
};
package.json будет содержать:
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
Команда docs:dev будет использоваться из <folder name>, корня вашего проекта, для просмотра сайта документации во время работы над ним. Он перезагружен в горячем режиме, поэтому при сохранении вы сразу видите свои изменения
Вторая команда будет использоваться нашим скриптом Travis для создания нашего статического сайта. Который мы сейчас настроим.
Откройте файл .travis.yml и скопируйте следующее:
language: node_js
node_js:
- "10"
env:
- CXX=g++-4.8
addons:
apt:
sources:
- ubuntu-toolchain-r-test
packages:
- g++-4.8
install:
- npm install -g vuepress
script:
- npm run docs:build
cache:
directories:
- "node_modules"
notifications:
email: false
deploy:
provider: pages
skip-cleanup: true
local_dir: docs/.vuepress/dist
github-token: $GITHUB_TOKEN # Set in the settings page of your repository, as a secure variable
repo: <username || or org name>/<publication repo name>
keep-history: true
target-branch: master
on:
branch: master
Сначала мы устанавливаем nodejs 10 по умолчанию, Travis устанавливает старую версию, и она несовместима с vuepress, для которого требуется nodejs ≥ 8. Затем Vuepress устанавливается глобально, мы запускаем сценарий сборки, который мы настроили ранее. Мы кэшируем node_modules так, что следующая сборка будет быстрее. Я не хочу получать электронное письмо от каждой сборки, поэтому отключил его здесь. Если вы хотите получать электронную почту, удалите ее.
Затем разворачиваем результат сборки. Обратите внимание, что мы берем только сгенерированный контент в папке dist. Для публикации в репо нам нужен токен git. Мы сделаем это дальше, но это имя переменной, которое мы будем использовать в Travis.
Затем мы устанавливаем repo, для которого мы хотим опубликовать и в какой ветке. Свойство keep-history очень важно. Без него вам нечего будет публиковать, поскольку Трэвис уже удалил файлы. Так что да, сохраните файлы, чтобы мы могли их куда-нибудь запихнуть;)
Для токена GitHub перейдите в настройки (в правом верхнем углу экрана - выпадающий список вашего аватара), в меню слева нажмите Developer Settings, затем Personal Access Tokens. Создайте новый. Вы можете увидеть это только один раз ... Так что скопируйте его, и теперь мы настроим Трэвиса. Если вы меня не поняли, на GitHub есть пошаговое руководство.
Теперь на вашем аккаунте Travis нам понадобятся:
- Подключите свою учетную запись Github
- Активируйте свой рабочий репозиторий
Когда это будет сделано, перейдите в настройки вашего проекта:
Вы можете найти это в раскрывающемся списке More options. Вы увидите следующий экран:
Здесь вы можете создать новую переменную среды. Создайте новый со значением GITHUB_TOKEN notice, без знака $ и в значение добавьте значение вашего вновь созданного токена GitHub. Убедитесь, что переключатель установлен как в красном поле. Это скроет значение переменной в журналах сборки. Это важно. Если не дадите кому нибудь доступ к вашему репозиторию.
Последний шаг, нам нужно настроить страницу GitHub. Зайдите в настройки вашего репозитория публикаций:
Прокрутите вниз до конфигурации страниц GitHub и установите:
Обратите внимание, что источником является master branch, и видите ли вы последний сегмент пути, выделенный красным? это имя вашего репозитория, и это свойство base, которое мы настроили в файле config.js.
Нормально все должно работать…. Да нормально. Создайте контент, добавив несколько файлов Markdown в вашу docs папку, затем внесите изменения, откиньтесь на спинку кресла и наслаждайтесь автоматической работой в цифровом мире.
