Publishing your site · Docusaurus

여러분은 이제 기본 사이트 구조 만들기와 로컬에서 실행하기를 성공적으로 수행했습니다. 이번에는 원하는 형태로 수정하기 과정을 통해 링크를 생성하고 다른 사용자에게 공개하는 방법을 살펴봅니다. 도큐사우르스는 정적인 HTML로 만들어진 웹사이트를 생성합니다. 생성된 HTML 파일을 여러분의 웹서버나 호스팅 업체에서 제공하는 공간에 옮기기만 하면 됩니다.

정적 HTML 페이지 만들기

여러분의 웹사이트 정적 빌드를 실행하기 위해서는 website 디렉토리 위치에서 아래 명령어를 실행합니다.

yarn run build # 또는 `npm run build`

명령어가 실행되면 build 디렉토리가 website 디렉토리 아래 생성됩니다. 생성된 디렉토리에는 작성한 문서가 .html 파일로 생성되며 pages 디렉토리 안에 있던 콘텐츠도 같이 생성됩니다.

정적 HTML 페이지 호스팅하기

이제 website/build 디렉토리에 생성된 모든 파일을 여러분이 선택한 웹서버 html 디렉토리 아래로 복사합니다.

예를 들어, Apache와 Nginx 모두 /var/www/html 기본 컨텐츠 제공 경로 입니다. 어떤 웹서버나 호스팅 업체를 사용할지는 도큐사우르스에서 권할 문제는 아니라 여기서 언급하지는 않겠습니다.

여러분의 웹서버에서 사이트를 서비스하는 경우에는 웹서버에서 적절한 HTTP 헤더값을 가지고 리소스 파일을 제공해주어야 합니다. CSS 파일은 헤더 content-type 값을 text/css으로 설정해야 합니다. Nginx의 경우는 nginx.conf 파일에 include /etc/nginx/mime.types; 을 설정하는 것을 의미합니다. See this issue for more info.

ZEIT Now 사용하기

도큐사우르스 프로젝트를 ZEIT Now에 배포하면 성능과 사용 편의성 측면에서 몇가지 이점이 제공 됩니다.

가장 중요한 건, 도큐사우르스 프로젝트를 배포하는데 겨우 몇초 밖에 걸리지 않는 것 입니다:

우선, Zeit Now의 command-line interface를 설치합니다:

npm i -g now

다음 명령어를 프로젝트 루트 디렉토리에서 실행하세요:

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 the now-examples repository for a Docusaurus project.

GitHub 페이지 활용하기

Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: GitHub Pages.

Deploying to GitHub Pages

Docusaurus supports deploying as project pages or user/organization pages, your code repository does not even need to be public.

코드 저장소가 프라이빗 상태라고 하더라도 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. 이렇게 하는 경우에는 도큐사우르스의 문서 구조를 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).

You will need to modify the file website/siteConfig.js and add the required parameters.

파라미터	설명
`organizationName`	코드 저장소를 소유하고 있는 GitHub 사용자 또는 그룹 계정입니다. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "facebook" GitHub organization.
`projectName`	프로젝트에서 사용하고 있는 GitHub 저장소의 이름입니다. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus".
`url`	Your website's URL. For projects hosted on GitHub pages, this will be "https://username.github.io"
`baseUrl`	Base URL for your project. For projects hosted on GitHub pages, it follows the format "/projectName/". For https://github.com/facebook/docusaurus, `baseUrl` is `/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 값을 지정하는 방법도 사용할 수 있습니다.

Now you have to specify the git user as an environment variable, and run the script 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"

환경 변수로 설정할 수 있는 추가적인 2가지 파라미터는 아래와 같습니다.

파라미터	설명
`USE_SSH`	`true`로 값을 설정하면 GitHub 저장소 연결 시 HTTPS 대신 SSH를 사용합니다. 변수값을 설정하지 않으면 HTTPS가 기본으로 설정됩니다.
`CURRENT_BRANCH`	배포될 최신 문서를 포함하고 있는 브랜치를 지정합니다. 일반적인 경우는 `master` 브랜치가 되겠지만, `gh-pages`를 제외한 어떤 브랜치(기본값 또는 다른)를 사용해도 괜찮습니다. 변수값을 설정하지 않으면 현재 브랜치를 사용합니다.

SSH 키 관련 문제가 발생한다면 GitHub's authentication documentation 페이지 정보를 참고하세요.

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 documentation 페이지 정보를 참고하세요.

문서를 수정해서 변경된 내용을 사이트에 배포하고자 한다면 위에 있는 명령어를 실행하기만 하면 됩니다. 문서의 변경이 거의 발생하지 않는다면 스크립트를 수동으로 실행하는 방식이 더 좋은 선택입니다. 수동으로 변경된 항목을 배포하는 것은 그리 귀찮은 일은 아닙니다.

하지만, 지속적인 통합(CI) 프로세스를 만들고자 한다면 자동으로 배포되는 작업을 구성할 수도 있습니다.

지속적인 통합 환경에서 자동으로 배포하기

지속적인 통합 (CI) 서비스는 소스 콘트롤에 새로운 커밋이 발생할때마다 반복적으로 발생하는 작업을 처리하기 위해 사용합니다. 지속적인 통합 환경에서는 단위 테스트, 통합 테스트, 자동 빌드, NPM 배포 그리고 변경된 내용을 웹사이트에 배포하기 같은 복합적인 작업을 처리할 수 있습니다. 자동화된 웹사이트 업데이트를 처리하기 위해서는 문서가 변경됐을때 publish-gh-pages 스크립트를 호출하기만 하면 됩니다. In the following section, we'll be covering how to do just that using CircleCI, a popular continuous integration service provider.

Using CircleCI 2.0

Circle Ci에 대한 정보가 필요하다면 setup CircleCI 페이지 정보를 참고하세요. 여러분의 사이트와 문서를 CircleCI를 통해 자동으로 배포하고자 한다면 publish-gh-pages 스크립트가 배포 단계에서 실행될 수 있도록 Circle 설정을 변경해주기만 하면 됩니다. 아래와 같은 단계로 설정을 변경할 수 있습니다.

GIT_USER에 설정한 GitHub 사용자 계정은 문서가 있는 저장소 쓰기 권한을 가지고 있어야 합니다. 저장소에서 Settings | Collaborators & teams 메뉴에서 설정을 변경할 수 있습니다.
GIT_USER에 지정한 사용자로 GitHub 사이트에 로그인합니다.
Https://github.com/settings/tokens URL로 접근해서 GIT_USER를 위한 personal access token을 생성합니다. 접근 범위 설정 시 repository를 선택하면 프라이빗 저장소에 대한 모든 권한을 부여할 수 있습니다. 생성한 토큰은 안전한 곳에 보관하고 외부에 노출되지 않도록 합니다. 토큰은 GitHub 비밀번호를 대신해 GitHub에서 처리하고자하는 모든 작업에 대한 인증 작업을 수행합니다.
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 그룹 계정/저장소로 변경합니다.
GITHUB_TOKEN라는 이름으로 새로운 환경 변수를 생성하고 앞에서 생성된 액세스 토큰을 값으로 지정합니다.
.circleci 이라는 이름으로 디렉토리를 생성하고 config.yml 파일을 만들어서 넣어줍니다.
아래에 있는 내용을 .circleci/config.yml 파일에 채워줍니다.

# If you only want 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: 항목에서 <....>로 표시된 부분은 적절한 값으로 변경해주어야 합니다. <GIT_USER> 항목은 GitHub 저장소에 문서를 집어넣기 위한 권한을 가지고 있는 GitHub 사용자 계정을 지정해줍니다. 대부분의 경우 <GIT_USER>와 <GITHUB_USERNAME>은 같은 값을 사용합니다.

DO NOT place the actual value of $GITHUB_TOKEN in circle.yml. We already configured that as an environment variable back in Step 5.

GitHub 저장소 접근 시 SSH를 사용하고자 한다면 USE_SSH=true을 설정하면 됩니다. SSH 설정을 적용하면 설정된 값은 다음과 같은 형식이 됩니다. cd website && npm install && GIT_USER=<GIT_USER> 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).

You can work around this by:

Setting the environment variable CUSTOM_COMMIT_MESSAGE flag to the publish-gh-pages command with the contents of [skip ci]. e.g.

CUSTOM_COMMIT_MESSAGE="[skip ci]" \
  yarn run publish-gh-pages # or `npm run publish-gh-pages`

Alternatively, you can work around this by creating a basic CircleCI config with the following contents:

# 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 파일로 만들고 website/static 디렉토리 밑에 있는 .circleci 디렉토리 아래에 저장합니다.

Travis CI 사용하기

Https://github.com/settings/tokens 에 접속해서 새로운 personal access token을 생성합니다.
GitHub 사용자 계정을 사용해 활성화하고자 하는 저장소에 Travis CI 앱을 추가합니다.
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.
GH_TOKEN라는 이름으로 새로운 환경 변수를 만들고 이전 단계에서 생성한 토큰을 값으로 지정합니다. 그리고 GH_EMAIL (이메일 주소), GH_NAME (GitHub 사용자 계정) 환경 변수값도 설정합니다.
저장소 루트에 아래 내용을 참고해 .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 스크립트가 실행되어 여러분의 웹사이트를 배포하게 됩니다.

Hosting on 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 활용하기

아래 단계를 따라 도큐사우르스로 만든 사이트를 Netlify에서 운영할 수 있습니다.

Select New site from Git
사용하고 있는 Git 서비스 공급자에 연결합니다.
배포할 브랜치를 선택합니다. 기본값은 master입니다.
빌드 단계의 세부 항목을 설정합니다.
- 빌드 명령어를 다음과 같이 입력합니다. cd website; npm install; npm run build;
- 배포할 디렉토리는 다음과 같습니다. website/build/<projectName> (projectName은 siteConfig에서 설정합니다).
Click Deploy site

Netlify 설정을 통해 저장소에 커밋이 발생할때마다 빌드를 처리할 수도 있고 master 브랜치에 커밋이 발생할때만 빌드가 실행될 수 있습니다.

Hosting on Render

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

Create a new Web Service on Render, and give Render's GitHub app permission to access your Docusaurus repo.
배포할 브랜치를 선택합니다. The default is master.
Enter the following values during creation.

Field Value

Environment Static Site

Build Command cd website; yarn install; yarn build

Publish Directory website/build/<projectName>

projectName is the value you defined in your siteConfig.js.
```
const siteConfig = {
  // ...
  projectName: 'your-project-name',
  // ...
```

Field	Value
Environment	`Static Site`
Build Command	`cd website; yarn install; yarn build`
Publish Directory	`website/build/<projectName>`

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 파일에 GitHub Enterprise 호스트이름을 설정하는 'githubHost' 속성을 추가합니다. 아니면, 환경 변수로 명령어 실행 시 GITHUB_HOST를 설정할 수 있습니다.