MDBook 및 GiitHubPages에서 문서 공개

MDBook 소개

Rust제 GitBook 라이카 도구입니다.
표기로 기술할 수 있고 온라인 책을 간단하게 제작할 수 있다.
러스트 좋아요.

Rust 설치

mdBook을 사용하기 위해 Rust의 포장 관리 도구인 카고를 설치합니다.

Ubuntu

curl https://sh.rustup.rs -sSf | sh

위 명령만 실행하면 설치할 수 있습니다.

Windows

https://visualstudio.microsoft.com/ja/downloads
BuildTools for Visual Studio 2019를 다운로드하고 Visual C++ Build Tool을 설치합니다.
이후 https://www.rust-lang.org/tools/install부터 시작한다.exe를 다운로드하고 실행합니다.
다음 명령 등을 실행하여 설치가 정상적인지 확인하세요.

cargo --version

mdBook 설치

Cargo 설치가 완료되면 다음 명령을 사용하여 mdBook을 설치합니다.

cargo install mdbook

이쪽에서도 아래 명령 등을 실행해 설치 여부를 확인한다.

mdbook --version

GiitHub 측의 준비

GiitHub에서는 GiitHubPages용 창고([User Name].github.io, 또는 설정에서 GiitHubPages용 창고)와 MDBook 프로젝트를 업로드하는 창고 2개를 준비했다.
그런 다음 저장소에 로그인할 SSH 키를 준비합니다.
gh-pages와 gh-pages.pub라는 두 개의 파일을 생성했기 때문에, 키(gh-pages.pub)를 GiitHubPages에 사용할 창고에 설정합니다DEPLOY_KEY라는 이름으로 등록해.
Allow write access 확인란을 선택합니다.

비밀 키(gh-pages)는 다른 창고의 Settings>Secrets에도 ACTIONS가 있습니다.DEPLOY_KEY라는 이름으로 등록해.

이로써 GiitHub 측의 준비는 끝났다.

로컬 준비

우선 적당한 폴더를 준비하고 이 폴더에서 다음 명령을 실행합니다.

ssh-keygen -t rsa -b 4096 -f gh-pages

다음과 같이 파일을 생성합니다.

mdbook init

북 디렉토리에 구축된 파일이 저장됩니다.
src 디렉토리에 Markdown 파일 그룹을 넣습니다.
SUMMARY.md에 적힌 내용은 부식이다.
실행mdbook build 후 파일을 구축하고 실행mdbook serve 후 src 이하의 파일을 감시하며 변경이 있으면 자동으로 재구성합니다.
그런 다음 GiitHubAction에서 자동 구문을 설정합니다.
.github 아래에 파일을 추가합니다.
추가된 디렉토리 구조는 다음과 같습니다.

mdBook
├── book
├── src
│  ├── chapter_1.md
│  └── SUMMARY.md
└── .gitignore(生成時に作成すると答えた場合)

제작 후 main.yml, Dockerfile에 다음과 같이 기재하십시오.
main.yml

mdBook
├── .github
│  ├── actions
│  │  └── build
│  │     └── Dockerfile
│  └── workflows
│     └── main.yml
├── book
├── src
│  ├── chapter_1.md
│  └── SUMMARY.md
└── .gitignore(生成時に作成すると答えた場合)

Dockerfile

name: CI/CD
on:
  push:
    branches:
    - master
    paths:
    - "src/**"
    - "book.toml"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Build
      uses: ./.github/actions/build
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        external_repository: [自分のユーザー名]/[GitHubPagesのリポジトリ名]
        PUBLISH_BRANCH: master
        PUBLISH_DIR: ./book

을 입력한 후 프로젝트에 Giit를 추가하고 업로드에 사용할 창고에 push하여 src 폴더나 북에 넣습니다.toml 변경 시 GiitHub Action을 실행하여 HTML 등 파일을 GiitHubPages용 창고에 자동으로 업로드합니다.

끝말

mdBook과 GiitHubPages를 이용하면 온라인북을 무료로 간단히 공개할 수 있다.
문서와 블로그 등은 널리 활용할 수 있을 것 같으니 꼭 잘 활용해 주십시오.