1.14.6

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 of seconds:

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

That's all. Your docs will automatically be deployed.

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 станет публичным.

Note: When you deploy as user/organization page, the publish script will deploy these sites to the root of the master branch of the username.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in another branch of the username.github.io repo (e.g., maybe call it source), or in another, separate repo (e.g. in the same as the documented source code).

  1. Вам потребуется изменить файл website/siteConfig.js и добавить необходимые параметры.
НаименованиеОписание
organizationNameGitHub пользователь или организация, являющаяся владельцем репозитория. Если вы владелец проекта, то эта настройка - наименование вашей учетной записи на GitHub. In the case of Docusaurus, that would be the "facebook" GitHub organization.
projectNameНаименование репозитория GitHub для вашего проекта. Например, исходный код Docusaurus размещен по адресу https://github.com/facebook/docusaurus, поэтому наш проект в этом случае будет называться «docusaurus».
urlURL-aдрес вашего сайта. For projects hosted on GitHub pages, this will be "https://username.github.io"
baseUrlБазовый URL-адрес для вашего проекта. For projects hosted on GitHub pages, it follows the format "/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. E.g. If your GitHub username is "user42" then user42.github.io, or in the case of an organization name of "org123", it will be org123.github.io.

Note: Not setting the url and baseUrl of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.

Хотя мы рекомендуем установить 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.

You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of https://username.github.io/projectName, or a custom domain if you have set that up. 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.
# If you only want the circle to run on direct commits to master, you can uncomment this out
# and uncomment the filters: *filter-only-master down below too
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # specify the version you desire here
      - 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; имеют одинаковые значения.

DO NOT place the actual value of $GITHUB_TOKEN in 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. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the More options > Setting > Environment Variables section of your repository.
  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.

Хостинг на 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. Select New site from Git

  2. Подключитесь к своему провайдеру Git.

  3. Выберите ветку для развертывания. По-умолчанию это master

  4. Настройте шаги сборки:

    • Для команды сборки введите: cd website; npm install; npm run build;
    • Для каталога публикации: website/build/&lt;projectName&gt; (используйте projectName из своего siteConfig)

  5. Click 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.

    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 →