next

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. Просмотрите это обращение для получения дополнительной информации.

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

Using Vercel

Deploying your Docusaurus project to Vercel 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 of seconds:

  1. First, install their command-line interface:
npm i -g vercel
  1. Запустите команду внутри корневого каталога вашего проекта:
vercel

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

Note that the directory structure Now supports is slightly different from the default directory structure of a Docusaurus project - The docs directory has to be within the website directory, ideally following the directory structure in this example. You will also have to specify a customDocsPath value in siteConfig.js. Take a look at the now-examples repository for a Docusaurus project.

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

Docusaurus was designed to work well with one of the most popular hosting solutions for open source projects: 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.

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

Bash

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

Windows

cmd /C "set "GIT_USER=<GIT_USER>"&& set CURRENT_BRANCH=master && set USE_SSH=true && yarn 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 "<GITHUB_USERNAME>@users.noreply.github.com"
            git config --global user.name "<YOUR_NAME>"
            echo "machine github.com login <GITHUB_USERNAME> password $GITHUB_TOKEN" > ~/.netrc
            cd website && yarn install && GIT_USER=<GIT_USER> 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. We already configured that as an environment variable back in Step 5.

Если вы желаете использовать 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.

Using Azure Pipelines

  1. Sign Up at Azure Pipelines if you haven't already.
  2. Create an organization and within the organization create a project and connect your repository from GitHub.
  3. Go to https://github.com/settings/tokens and generate a new personal access token with repository scope.
  4. In the project page (which looks like https://dev.azure.com/ORG_NAME/REPO_NAME/_build) create a new pipeline with the following text. Also, click on edit and add a new environment variable named GH_TOKEN with your newly generated token as its value, then GH_EMAIL (your email address) and GH_NAME (your GitHub username). Make sure to mark them as secret. Alternatively, you can also add a file named azure-pipelines.yml at yout repository root.
# azure-pipelines.yml
trigger:
  - master

pool:
  vmImage: 'ubuntu-latest'

steps:

  - checkout: self
    persistCredentials: true

  - task: NodeTool@0
    inputs:
      versionSpec: '10.x'
    displayName: 'Install Node.js'

  - script: |
      git config --global user.name "${GH_NAME}"
      git config --global user.email "${GH_EMAIL}"
      git checkout -b master
      echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
      cd website
      yarn install
      GIT_USER="${GH_NAME}" CURRENT_BRANCH=master yarn run publish-gh-pages
    env:
      GH_NAME: $(GH_NAME)
      GH_EMAIL: $(GH_EMAIL)
      GH_TOKEN: $(GH_TOKEN)
    displayName: 'yarn install and build'

Using Drone

  1. Create a new ssh key that will be the deploy key for your project.
  2. Name your private and public keys to be specific and so that it does not overwrite your other ssh keys.
  3. Go to https://github.com/USERNAME/REPO/settings/keys and add a new deploy key by pasting in our public key you just generated.
  4. Open your Drone.io dashboard and login. The URL looks like https://cloud.drone.io/USERNAME/REPO.
  5. Click on the repository, click on activate repository, and add a secret called git_deploy_private_key with your private key value that you just generated.
  6. Create a .drone.yml on the root of your repository with below text.
# .drone.yml
kind: pipeline
type: docker
trigger:
  event:
    - tag
- name: Website
  image: node
  commands:
    - mkdir -p $HOME/.ssh
    - ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts
    - echo "$GITHUB_PRIVATE_KEY > $HOME/.ssh/id_rsa"
    - chmod 0600 $HOME/.ssh/id_rsa
    - cd website
    - npm i
    - npm run publish-gh-pages
  environment:
    USE_SSH: true
    GIT_USER: $DRONE_COMMIT_AUTHOR
    GITHUB_PRIVATE_KEY: git_deploy_private_key

Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website.

Hosting on Vercel

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

To deploy your Docusaurus project with a Vercel for Git Integration, make sure it has been pushed to a Git repository.

Import the project into Vercel using the Import Flow. During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found here.

After your project has been imported, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly "main") will result in a Production Deployment.

Хостинг на 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)

  5. Нажмите на Deploy site

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

Хостинг на Render

Render offers free static site hosting with fully managed SSL, custom domains, a global CDN and continuous auto deploy from your Git repo. Deploy your app in just a few minutes by following these steps.

  1. Create a new Web Service on Render, and give Render's GitHub app permission to access your Docusaurus repo.

  2. Выберите ветку для развертывания. The default is master.

  3. Enter the following values during creation.

FieldValue
EnvironmentStatic Site
Build Commandcd website; yarn install; yarn build
Publish Directorywebsite/build/<projectName>

projectName is the value you defined in your siteConfig.js.

javascript{7}
   const siteConfig = {
     // ...
     projectName: 'your-project-name',
     // ...

That's it! Your app will be live on your Render URL as soon as the build finishes.

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

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

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

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

← Creating your siteDocker →