Question

개발 언어의 설명 매뉴얼이나 질문에 대한 답변을 마크다운(MD) 문서로 작성하고 호스팅하려면, 앞서 언급한 Docusaurus나 MkDocs 같은 도구가 매우 적합합니다. 이들 도구를 사용하면 쉽게 마크다운 문서를 기반으로 정적 사이트를 구축하고, 로컬 및 원격 서버에 호스팅할 수 있습니다. 여기에 따라 할 수 있는 구체적인 단계와 호스팅 방법을 설명드리겠습니다.

1. Docusaurus로 매뉴얼 사이트 구축하기

Docusaurus 설치 및 프로젝트 시작

1. Node.js 설치

   • Docusaurus는 Node.js 환경에서 동작하므로, 먼저 Node.js를 설치하세요.

2. Docusaurus 설치

   npx create-docusaurus@latest my-docs classic
   cd my-docs
   npm install
   

3. 마크다운 파일 작성

   • docs 폴더에 마크다운 파일을 추가하여 문서를 작성합니다. 예를 들어 getting-started.md 파일을 만들고 다음과 같이 작성합니다:

   # Getting Started
   
   여기에 개발 언어 설명을 작성합니다.
   
   ## 질문과 답변
   
   **Q: 이 언어의 주요 특징은 무엇인가요?**
   A: 이 언어는 ...
   

4. 로컬에서 실행

   npm start
   

   • 명령어를 실행하면 브라우저에서 http://localhost:3000을 통해 문서를 미리볼 수 있습니다.

5. 정적 사이트 빌드

   npm run build
   

   • build 폴더에 정적 파일이 생성되며, 이를 호스팅 서버에 업로드할 수 있습니다.

호스팅 옵션

• GitHub Pages: 무료로 GitHub 저장소에 정적 사이트를 호스팅할 수 있습니다.

  • docusaurus.config.js에서 baseUrl과 organizationName, projectName 설정을 맞춘 후, 다음 명령어로 배포합니다:

    GIT_USER=<Your GitHub Username> npm run deploy
    

• Vercel 또는 Netlify: 이 서비스들은 Docusaurus와 같은 정적 사이트를 쉽게 배포할 수 있습니다.

  • Vercel: https://vercel.com
  • Netlify: https://netlify.com

2. MkDocs로 매뉴얼 사이트 구축하기

MkDocs 설치 및 프로젝트 시작

1. MkDocs 설치

   • 먼저 Python이 필요하므로 Python을 설치하세요. 그런 다음 MkDocs를 설치합니다:

     pip install mkdocs
     

2. MkDocs 프로젝트 시작

   mkdocs new my-docs
   cd my-docs
   

3. 마크다운 파일 작성

   • docs 폴더에 마크다운 파일을 작성하고, 이를 문서화합니다. 예를 들어 index.md 파일에 다음과 같이 작성할 수 있습니다:

   # 개발 언어 매뉴얼
   
   ## 소개
   이 섹션에서는 언어의 주요 기능과 문법을 설명합니다.
   
   ## 자주 묻는 질문
   **Q: 이 언어의 사용법은 어떻게 되나요?**
   A: 이 언어는...
   

4. 로컬 서버에서 실행

   mkdocs serve
   

   • http://localhost:8000에서 문서를 미리볼 수 있습니다.

5. 정적 파일 빌드

   mkdocs build
   

   • site 폴더에 생성된 파일을 호스팅 서버에 업로드하여 배포할 수 있습니다.

호스팅 옵션

• GitHub Pages: MkDocs도 GitHub Pages에 쉽게 배포할 수 있습니다.

  mkdocs gh-deploy
  

• Vercel, Netlify 또는 다른 CDN 기반 서비스에서도 쉽게 배포 가능.

3. GitBook (추가 옵션)

GitBook도 좋은 선택입니다. GitBook은 실시간 협업 기능을 제공하여 여러 개발자나 팀원이 동시에 매뉴얼을 작성하고 관리할 수 있으며, 마크다운 형식의 문서를 바로 호스팅할 수 있습니다. 설정이 매우 간편하며, 웹 기반으로 문서 관리를 할 수 있습니다. GitBook으로 호스팅을 원하면 GitBook 공식 사이트에서 바로 시작할 수 있습니다.

결론

Docusaurus와 MkDocs는 마크다운 기반의 정적 사이트 생성을 위해 매우 적합한 오픈소스 도구입니다. GitHub Pages, Vercel, Netlify 같은 무료 호스팅 옵션을 사용하면 매뉴얼이나 질문/답변 문서를 쉽게 온라인에 공개할 수 있습니다.