Docusaurus로 아름다운 문서 웹사이트 구축

훌륭한 문서 웹사이트는 소프트웨어에 대해 많은 것을 말해줍니다. 사용자에게 소프트웨어 사용 방법을 알려줍니다. 개발자에게 소프트웨어가 무엇을 할 수 있고 어떻게 개발되는지 알려줍니다. 요컨대 개발자에게 필수품입니다.

그러나 상세하고 우수한 문서 웹 사이트를 만드는 데는 너무 많은 시간과 노력이 필요합니다. 특히 문서 작성 대신 개발에 집중하기를 원하기 때문입니다.

이 기사에서는 React로 구동되고 Markdown을 사용하여 문서를 작성하는 사용하기 쉬운 문서 사이트 생성기인 Facebook의 Docusaurus을 소개하고자 합니다.

Docusaurus: 간단하면서도 우아한 솔루션

Docusaurus는 문서를 Markdown으로 작성할 수 있는 오픈 소스 프로젝트로 시각적으로 매력적인 문서 웹 사이트를 즉시 사용자 지정하고 만들 수 있는 엄청난 유연성을 제공합니다!

1. 시작하기

다음 명령을 실행하여 새 설명서 사이트를 만듭니다.

npx @docusaurus/init@latest latest [name] classic

루트 폴더로 이동하여 npm start를 실행합니다. 귀하의 아름다운 새 사이트가 성공적으로 생성되었습니다.



클래식 템플릿은 루트 디렉터리에 다음 파일을 생성합니다.

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

초보자에게는 상당히 어렵게 보일 수 있으므로 이 템플릿을 사용하여 자신만의 문서 웹 사이트를 쉽게 사용자 지정하고 만드는 방법에 대해 논의해 보겠습니다.

2. 사이드바 커스터마이징

자신의 문서에 맞게 문서 사이드바를 쉽게 사용자 정의할 수 있습니다.

예제 사이드바는 다음과 같습니다.



기본 사이드바는 sidebar.js 인 someSidebar 의 값을 업데이트하기만 하면 이 사이드바를 사용자 지정할 수 있습니다.

module.exports = {
  someSidebar: {
    Docusaurus: ['doc1', 'doc2', 'doc3'],
    Features: ['mdx'],
  },
};

Docusaurus 및 Features는 사이드바의 드롭다운 범주를 나타내며 문자열 배열(예: doc1, doc2, doc3, mdx)은 사이트의 docs 폴더에 있는 마크다운 문서입니다.

예를 들어 카테고리 이름을 변경하고 대신 "doc3"를 아래 카테고리로 이동하면 됩니다.

module.exports = {
  someSidebar: {
    Introduction: ["doc1", "doc2"],
    About: [ "doc3", "mdx"],
  },
};

이제 사이드바는 다음과 같이 표시됩니다.

3. 구성

템플릿의 이름과 태그라인을 변경하는 것은 Docusaurus로 문서 웹사이트를 구축할 때 가장 먼저 해야 할 일입니다.
docusaurus.config.js에서 필요에 따라 무엇이든 구성할 수 있습니다.

다음은 맞춤설정할 수 있는 항목에 대한 스니펫입니다.

  title: 'My Site',
  tagline: 'The tagline of my site',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.

이 파일에서 탐색 모음 및 바닥글 링크를 사용자 지정할 수도 있습니다. 다음으로 탐색 모음을 사용자 지정하는 방법을 살펴보겠습니다.

4. 내비바 커스터마이징

기본적으로 탐색 모음에는 사이트 이름, 문서 링크 및 블로그 링크가 표시됩니다.

정보 페이지를 만들고 탐색 모음의 페이지에 대한 링크를 추가한다고 가정해 보겠습니다. about.md 디렉토리에 /pages 파일을 만들 수 있습니다.

모든 Markdown 문서에는 about.md에 id가 있어야 합니다. id를 지정하고 샘플 라인을 작성할 수 있습니다.

---
id: about
---

## This is my About page.

그런 다음 docusaurus.config.js에서 이 페이지 ID를 navbar 개체, items 배열에 추가하기만 하면 됩니다.

navbar: {
   items: [
     //...
     {to: 'about', label: 'About', position: 'left'}, //add this line
     //...
   ],
}

이제 렌더링된 사이트의 탐색 모음에 정보 페이지가 있습니다.

아름다운 문서 작성을 위한 무한한 가능성

Docusaurus를 사용하면 문서를 작성하고 필요에 맞게 템플릿을 쉽게 사용자 지정할 수 있습니다. 자세한 내용은 documentation website을 참조하십시오.

Docusaurus로 만든 잘 알려진 문서 사이트는 Prettier , React Native 및 mailgo 입니다. more을 보고 다음 문서 웹 사이트를 만들고 디자인하는 데 영감을 얻으십시오.

Here is my documentation website for a project I made: https://victoria-lo.github.io/Gameo/

읽어 주셔서 감사합니다! 도움이 되는 글이 되었기를 바랍니다! 그렇다면 기사를 좋아하고 공유하는 것을 잊지 마십시오. 다음 시간까지, 건배!