1.10.x

Translate

Publishing your site

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

Создание статических HTML страниц

Чтобы создать статическую сборку своего веб-сайта, запустите следующую команду из каталога website:

yarn run build # или `npm run build`

В результате будет создан каталог build внутри каталога website, содержащий файлы .html для всех документов и других страниц, размещенных в pages.

Хостинг статических HTML страниц

На этом этапе вы можете взять все файлы из каталога website/build и скопировать их в каталог html на вашем любимом веб-сервере.

Например, Apache и Nginx обслуживают содержимое каталога /var/www/html по-умолчанию. Впрочем, выбор веб-сервера или провайдера выходит за рамки Docusaurus.

При предоставлении доступа к своему сайту через ваш собственный веб-сервер, убедитесь, что сервер передает статические ресурсы с корректными HTTP заголовками. Файлы css должны быть переданы с заголовком content-type, имеющий значение text/css. В случае Nginx это значит, что вам следует добавить строку include /etc/nginx/mime.types; в файл nginx.conf. Просмотрите это обращение для получения дополнительной информации.

Хостинг на сервисах:

Использование ZEIT Now

Deploying your Docusaurus project to ZEIT Now will provide you with various benefits in the areas of performance and ease of use.

Most importantly, however, deploying a Docusaurus project only takes a couple seconds:

  1. Сначала установите интерфейс командной строки:
npm i -g now
  1. Запустите команду внутри корневого каталога вашего проекта:
now

Это все. Ваша документация будет автоматически развернута.

Использование GitHub Pages

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

Развертывание на GitHub Pages

  1. Docusaurus поддерживает развертывание сайта как Project Pages или User/Organization Pages, вашему репозиторию с кодом при этом даже не нужно быть публичным.

Даже если ваш репозиторий является приватным, все, что публикуется в ветке gh-pages станет публичным.

Примечание: Когда вы разворачиваете сайт как страницы пользователя/организации, сценарий публикации развернет эти сайты в корень ветки master репозитория username.github.io. В этом случае, обратите внимание, что вам понадобится инфраструктура Docusaurus, ваша документация и т. д. либо в другой ветви репозитория username.github.io (например, source), либо в другом отдельном репозитории (например, в том же, где размещен документируемый исходный код).

  1. Вам потребуется изменить файл website/siteConfig.js и добавить необходимые параметры.
НаименованиеОписание
organizationNameGitHub пользователь или организация, являющаяся владельцем репозитория. Если вы владелец проекта, то эта настройка - наименование вашей учетной записи на GitHub. В случае Docusaurus, это организация GitHub "facebook".
projectNameНаименование репозитория GitHub для вашего проекта. Например, исходный код Docusaurus размещен по адресу https://github.com/facebook/docusaurus, поэтому наш проект в этом случае будет называться «docusaurus».
urlURL-aдрес вашего сайта. Для проектов, размещенных на GitHub pages, это значение должно быть равным "https://username.github.io"
baseUrlБазовый URL-адрес для вашего проекта. Для проектов, размещенных на GitHub pages, это значение должно иметь вид "/projectName/". Для https://github.com/facebook/docusaurus, baseUrl равен /docusaurus/.
 
const siteConfig = {
  ...
  url: 'https://__userName__.github.io', // Your website URL
  baseUrl: '/testProject/',
  projectName: 'testProject',
  organizationName: 'userName'
  ...
}

In case you want to deploy as a user or organization site, specify the project name as <username>.github.io or <orgname>.github.io. Например, если ваша учетная запись на GitHub назвается "user42", то user42.github.io, или если наименование организации - "org123", то org123.github.io.

Примечание: Если вы не укажете url и baseUrl для своего проекта, то пути к файлам могут быть созданы неправильно, в результате чего ссылки на ресурсы, такие как стили и изображения, окажутся сломанными.

Хотя мы рекомендуем установить projectName и organizationName в siteConfig.js, вы также можете использовать переменные окружения ORGANIZATION_NAME и PROJECT_NAME.

  1. Теперь вы должны указать пользователя git как переменную окружения и запустить сценарий publish-gh-pages
НаименованиеОписание
GIT_USERИмя пользователя для учётной записи GitHub, которая имеет доступ к данному репозиторию. Для ваших собственных репозиториев это будет обычное имя пользователя GitHub. Указанный GIT_USER должен иметь доступ к хранилищу, указанному в комбинации organizationName и projectName.

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

GIT_USER=<GIT_USER> \
  CURRENT_BRANCH=master \
  USE_SSH=true \
  yarn run publish-gh-pages # или `npm run publish-gh-pages`

Есть также два необязательных параметра, которые задаются в качестве переменных окружения:

НаименованиеОписание
USE_SSHЕсли задано значение true, то используется SSH вместо HTTPS для подключения к репозиторию GitHub. HTTPS используется по умолчанию, если эта переменная не задана.
CURRENT_BRANCHВетвь, содержащая последние изменения для документов, которые будут развернуты. Обычно используется ветвь master, но это может быть любая ветвь (default или любая другая) за исключением gh-pages. Если значение не указано, будет использована текущая ветвь.

Если вы столкнулись с проблемами, связанными с ключами SSH, посетите документацию по авторизации на GitHub.

Теперь вы сможете загрузить свой веб-сайт, посетив его URL-адрес на GitHub Pages, который может выглядеть примерно так: https://username.github.io/projectName, или пользовательский домен, если вы его настроили. For example, Docusaurus' own GitHub Pages URL is https://facebook.github.io/Docusaurus because it is served from the gh-pages branch of the https://github.com/facebook/docusaurus GitHub repository. However, it can also be accessed via https://docusaurus.io/, via a generated CNAME file which can be configured via the cname siteConfig option.

Мы настоятельно рекомендуем ознакомиться с документацией GitHub Pages, чтобы узнать больше о том, как работает это решение для хостинга.

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

Однако вы можете автоматизировать процесс публикации с помощью непрерывной интеграции (CI).

Автоматизация развертываний с использованием непрерывной интеграции

Службы непрерывной интеграции (CI) обычно используются для выполнения рутинных задач всякий раз, когда новые коммиты регистрируются в системе контроля версий. Этими задачами могут быть любое сочетание запуска модульных и интеграционных тестов, автоматизации сборок, публикации пакетов в NPM и, конечно же, развертывания изменений на вашем веб-сайте. Все, что вам нужно сделать для автоматизации развертывания вашего сайта, - это запускать сценарий publish-gh-pages всякий раз, когда ваши документы обновляются. В следующем разделе мы расскажем, как это сделать, используя Circle CI, популярного поставщика услуг непрерывной интеграции.

Using CircleCI 2.0

Если вы еще этого не сделали, вы можете установить CircleCI для своего проекта с открытым исходным кодом. После этого, чтобы включить автоматическое развертывание вашего сайта и документации через CircleCI, просто настройте Circle для запуска сценария publish-gh-pages на этапе развертывания. Для настройки вы можете выполнить следующие шаги.

  1. Убедитесь, что учетная запись GitHub, которая будет установлена как GIT_USER, имеет права на запись в репозитории, содержащем документацию, проверив Settings | Collaborators & teams в репозитории.
  2. Войдите в GitHub как GIT_USER.
  3. Перейдите в https://github.com/settings/tokens для GIT_USER и создайте новый токен личного доступа, предоставив ему полный контроль над частными репозиториями через доступ к repository. Храните этот токен в безопасном месте, не передавая его никому. Этот токен может использоваться для аутентификации действий на GitHub от вашего имени вместо вашего пароля на GitHub.
  4. Open your CircleCI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". URL выглядит как https://circleci.com/gh/ORG/REPO/edit#env-vars, где «ORG / REPO» должен быть заменен вашей собственной организацией/репозиторием на GitHub.
  5. Создайте новую переменную среды с именем GITHUB_TOKEN, используя в качестве значения вновь созданный токен доступа.
  6. Создайте каталог .circleci и config.yml в этом каталоге.
  7. Скопируйте приведенный ниже текст в .circleci/config.yml.
# Если вы желаете запускать circle только на прямых коммитах в master, вы можете раскомментировать эту секцию
# также раскомментируйте строку filters: *filter-only-master ниже
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # укажите здесь версию, которую желаете использовать

      - image: circleci/node:8.11.1

    steps:

      - checkout
      - run:
          name: Deploying to GitHub Pages
          command: |
            git config --global user.email "&lt;GITHUB_USERNAME&gt;@users.noreply.github.com"
            git config --global user.name "&lt;YOUR_NAME&gt;"
            echo "machine github.com login &lt;GITHUB_USERNAME&gt; password $GITHUB_TOKEN" > ~/.netrc
            cd website && yarn install && GIT_USER=&lt;GIT_USER&gt; yarn run publish-gh-pages

workflows:
  version: 2
  build_and_deploy:
    jobs:

      - deploy-website:
#         filters: *filter-only-master

Обязательно замените все <....> в последовательности command: соответствующими значениями. Для &lt;GIT_USER&gt; это должна быть учетная запись GitHub, которая имеет доступ к записи документации в ваш репозиторий GitHub. В большинстве случаев &lt;GIT_USER&gt; и &lt;GITHUB_USERNAME&gt; имеют одинаковые значения.

НЕ помещайте фактическое значение $GITHUB_TOKEN в circle.yml. Мы уже настроили это как переменную среды еще на Шаге 3.

Если вы желаете использовать SSH для подключения к своему репозиторию GitHub, вы можете указать USE_SSH=true. Таким образом, команда выше будет выглядеть следующим образом: cd website && npm install && GIT_USER=&lt;GIT_USER&gt; USE_SSH=true npm run publish-gh-pages.

Unlike when you run the publish-gh-pages script manually when the script runs within the Circle environment, the value of CURRENT_BRANCH is already defined as an environment variable within CircleCI and will be picked up by the script automatically.

Теперь, когда новый коммит будет отправлен в master, CircleCI запустит набор тестов и, если все они будут пройдены, развернет ваш сайт с помощью сценария publish-gh-pages.

If you would rather use a deploy key instead of a personal access token, you can by starting with the CircleCI instructions for adding a read/write deploy key.

Советы и трюки

When initially deploying to a gh-pages branch using CircleCI, you may notice that some jobs triggered by commits to the gh-pages branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).

Вы легко можете обойти это следующим образом:

  • Установите значение переменной окружения CUSTOM_COMMIT_MESSAGE для сценария publish-gh-pages равной [skip ci]. Например:
CUSTOM_COMMIT_MESSAGE="[skip ci]" \
  yarn run publish-gh-pages # или `npm run publish-gh-pages`
  • Кроме того, вы можете обойти эту проблему, создав базовый файл настроек CircleCI со следующим содержимым:
# CircleCI 2.0 Config File
# This config file will prevent tests from being run on the gh-pages branch.
version: 2
jobs:
  build:
    machine: true
    branches:
      ignore: gh-pages
    steps:
      - run: echo "Skipping tests on gh-pages branch"

Сохраните этот файл как config.yml и разместите его в каталоге .circleci внутри вашего каталога website/static.

Использование Travis CI

  1. Перейдите по ссылке https://github.com/settings/tokens и создайте новый персональный токен доступа
  2. Используя свою учетную запись GitHub, добавьте приложение Travis CI к репозиторию, который вы желаете активировать.
  3. Откройте панель Travis CI. URL выглядит как https://travis-ci.com/USERNAME/REPO, затем перейдите в секцию More options > Setting > Environment Variables своего репозитория.
  4. Создайте новую переменную окружения с именем GH_TOKEN и присвойте ей в качестве значения созданный токен, затем также создайте переменные GH_EMAIL (ваш email адрес) и GH_NAME (имя вашей учетной записи GitHub).
  5. Создайте файл .travis.yml в корне своего репозитория со следующим текстом.
# .travis.yml
language: node_js
node_js:
  - '8'
branches:
  only:
    - master
cache:
  yarn: true
script:
  - git config --global user.name "${GH_NAME}"
  - git config --global user.email "${GH_EMAIL}"
  - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
  - cd website && yarn install && GIT_USER="${GH_NAME}" yarn run publish-gh-pages

Теперь, когда новый коммит будет отправлен в master, Travis CI запустит набор тестов и, если все они будут пройдены, развернет ваш сайт с помощью сценария publish-gh-pages.

Хостинг на ZEIT Now

With ZEIT Now, you can deploy your site and connect it to GitHub or GitLab to automatically receive a new deployment every time you push a commit.

Хостинг на Netlify

Шаги по настройке вашего Docusaurus-сайта на Netlify.

  1. Выберите New site from Git
  2. Подключитесь к своему провайдеру Git.
  3. Выберите ветку для развертывания. По-умолчанию это master
  4. Настройте шаги сборки:
  • Для команды сборки введите: cd website; npm install; npm run build;
  • Для каталога публикации: website/build/&lt;projectName&gt; (используйте projectName из своего siteConfig)
  1. Нажмите на Deploy site

Вы также можете настроить Netlify для построения сайта после каждого коммита в вашем репозитории, или только для коммитов в ветке master.

Публикация на GitHub Enterprise

Публикация на GitHub Enterprise должна работать по той же схеме, что и на github.com; вам только лишь нужно определить хост организации на GitHub Enterprise.

НаименованиеОписание
GITHUB_HOSTИмя хоста для сервера GitHub enterprise.

Добавьте в siteConfig.js поле 'githubHost', которое будет содержать наименование хоста на GitHub Enterprise. Также вместо этого вы можете указать переменную окружения GITHUB_HOST при вызове команды публикации.

← Creating your siteDocker →