도큐사우루스 문서 사이트 만들기 - 2. 설치

도큐사우루스를 이용하여 좀 더 체계적으로 기술적인 자료나 매뉴얼들을 적어두는 온라인 문서 사이트를 하나 만들어 보자. 서비스 운영 배포가 무료인 GitHub Pages 기술을 활용해서 아무런 비용없이 문서 사이트를 운영해 보자.

 

도큐사우루스에 대해서는, 설치 부터 운영까지의 내용을 아래와 같이 정리하고 있다.

2024.01.02 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 1. 소개

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 2. 설치 혹은 GitHub Fork로 복사

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 3. GitHub Actions 빌드 및 브랜치 생성

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 4. GitHub Pages 배포 자동화

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 5. GitHub Pages 도메인 연동하기

2024.01.11 - [도큐사우루스] - 도큐사우루스 문서 사이트 만들기 - 6. 다국어 처리

 

이제 도큐사우루스를 설치하고 배포해서 데모 페이지까지 만들어 보자.

GitHub Fork 복사해서 간단 설치

배포용으로 만들 것이므로, 로컬에 설치하는 일반적인 방법은 무시하자. 아주 쉽게 GitHub 계정만 있으면 할 수 있도록 하겠다.

yarn, npm 이런거 말고 온라인에서 바로 되도록, 이 저장소를 fork 하는 것으로 해결되도록 합니다. 설치가 머예요? 버튼 한 번 누르면 끝!!

그리고, 자신이 복사한 레포지토리를 다운로드 하거나 git clone 해서 작업 폴더로 가져오면 끝!!

설치며 이런 과정이 필요없게 딱 다 들어 있으니 그냥 복사만 하면 됩니다.

GitHub의 Fork 를 이용하면 진짜 클릭 한방에 자신의 온라인 문서 사이트를 갖게 되는 것이 너무 최고네요 :)

 

매번 세팅이 바뀌어서, 이방법은 권하지 않아요. 설치후 자기 repo 만들어서 올리는 것을 권고합니다.

 

docusaurus.config.js 세팅 변경

폴더내에 있는 docusaurus.config.js 파일의 세팅을 자신의 것에 맞게 변경해야 한다. 

원본 글에 보면 많은 설명이 잘 되어 있다.

https://docusaurus.io/docs/deployment#docusaurusconfigjs-settings

Deployment | Docusaurus

간단하게 docusaurus.config.js 파일내에 아래 url, baseUrl 만 바꿔서 사용했다.

const config = {
...
  // Set the production url of your site here
  // url: 'https://your-docusaurus-site.example.com',
  url: 'https://자신의GitHub아이디.github.io/',
  // Set the /<baseUrl>/ pathname under which your site is served
  // For GitHub pages deployment, it is often '/<projectName>/'
  // baseUrl: '/',
  baseUrl: '/docusaurus-easy/',
...
};

 

설치 후 로컬 구현 - 테스트

필요없습니다. 아닌가?

그래도 제대로 나오는지 확인하기 위해 설정을 간단하게 로컬 피씨에서 실행하는 정도의 명령어를 정리해 둘 필요가 있어 보이네요.

GitHub 에서 다운로드 한 후에 압축을 풀던지, 아니면 git clone 해서 해당 폴더로 이동한 후 아래 명령만 치면 로컬에서도 해당 문서 사이트를 살펴 볼 수 있습니다. 

npm 방식의 실행법만 살펴보겠습니다. npm, Yarn, pnpm 다 할 수 있는데 자세한 내용은 여길 방문해 보세요.,

https://docusaurus.io/docs/installation#running-the-development-server

npm run start

 

기본적으로 http://localhost:3000 이 주소로 브라우저가 오픈됩니다. 

실행하면 바로 브라우저가 떠서 해당 페이지가 오픈됩니다. 소스를 저장하면 자동 반영되네요.

도큐사우루스 로컬 실행 화면

위 그림처럼 나오면 성공!!!!

url를 보면 세팅에서 바뀐 baseUrl 주소가 나옴을 볼 수 있다.

Requirements​

로컬 실행을 위해서는 Node 가 설치되어 있어야 합니다. 아래 링크로 들어가서 설치해주세요

• Node.js version 18.0 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed.
  • When installing Node.js, you are recommended to check all checkboxes related to dependencies.

직접 설치

참고로 남겨운다. 당연히 직접 해보고 싶은 사람들도 있을 것 같다. 혹시나 해서 직접 만든 스크립트 로그를 남겨둡니다.

명령 하나면 다 되니깐 쉽기도 쉽네.

다음 깃헙 액션, 깃헙 페이지를 이용한 자동 배포를 하는 예제에서는 쓰지 못하고 스스로 해결할 사람은 아래 로그를 보고 따라가보세요.

$ npm init docusaurus
$ cd mydocs
$ npm start

사실 명령어는 기본 3개다. 위의 명령을 치면서 묻는대로 답하면 사이트가 뚝딱 만들어 진다.

$ npm init docusaurus
√ What should we name this site? ... mydocs
√ Select a template below... » classic (recommended)
? This template is available in TypeScript. Do you want to use the TS variant? » (y/N)
√ This template is available in TypeScript. Do you want to use the TS variant? ... no
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...
npm WARN deprecated stable@0.1.8: Modern JS already guarantees Array#sort() is a stable sort, so this library is deprecated. See the compatibility table on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#browser_compatibility

added 1209 packages, and audited 1210 packages in 51s

293 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
[SUCCESS] Created mydocs.
[INFO] Inside that directory, you can run several commands:

  `npm start`
    Starts the development server.

  `npm run build`
    Bundles your website into static files for production.

  `npm run serve`
    Serves the built website locally.

  `npm run deploy`
    Publishes the website to GitHub pages.

We recommend that you begin by typing:

  `cd mydocs`
  `npm start`

Happy building awesome websites!

User1@B MINGW64 ~/Documents/Work/docusaurus-easy (main)
$ cd mydocs

User1@B MINGW64 ~/Documents/Work/docusaurus-easy/mydocs (main)
$ npm start

> mydocs@0.0.0 start
> docusaurus start

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

✔ Client
  Compiled successfully in 6.18s

client (webpack 5.89.0) compiled successfully

 

빌드

빌드 방법은 로컬 테스트일 경우에 확인용으로 한 번 해보길 바라며, 아래 GitHub Pages 배포하기를 해두면 그냥 문서 내용만 수정해서 Git Push 만 하면 자동 빌드 및 배포 되도록 설정할 겁니다.

Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:

npm run build

 

and contents will be generated within the /build directory, which can be copied to any static file hosting service like GitHub pages, Vercel or Netlify. Check out the docs on deployment for more details.

 

여기에 적힌것 대로, 빌드한 이후 이 빌드 결과물 즉 /build 디렉토리만 따로 GitHub Pages로 수동 배포해도 자신의 온라인 문서시스템을 가질수 있습니다.

깃헙액션이 생긴이후로 이 작업을 매번 수동으로 할 필요없이 자동으로 빌드 배포를 수행하도록 할 수 있습니다. 난 그냥 문서만 수정해서 Git Push 하면 끝!!

 

지금까지 도큐사우루스를 그냥 GitHub Fork를 통해 가져와서 설치 실행하는 방법을 살펴 보았습니다. 이제 온라인으로 배포해서 365일 24시간 웹 호스팅 없이도 무료로 운용되는 자신만의 문서 사이트를 가져봅시다. :)