Docusaurus를 사용한 Doc as a code Deploy 검토하기

Doc as a code 요구사항

Doc as a code Deploy를 위해서 요구사항을 기반으로 우리 부서에서 사용 가능한지 검토해보려고합니다.

가장 최신버전인 Docusaurus v3.4.0를 기반으로 확인 해 보려고 합니다.

 

1. multi-repository의 markdown 파일들에 대해서도 쉽게 indexing 제공

각 폴더마다 _category_.json을 포함해야하는것으로 보입니다.

{
  "label": "Packer",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "5 minutes to learn the most important Docusaurus concepts."
  }
}

이런 파일들을 추가하면 하위 폴더에 있는 모든 markdown 파일들을 그대로 출력해주는듯하네요.

다만 우리가 원했던 hierarchy 기능은 지원하려면 조금 더 복잡한 과정이 필요한거같네요.

 

아래의 예시 사이트에서 찾아본 결과로는 Hierarchy 구조는 가능해 보입니다.

Client Setup | Dyte Docs

Client Setup이 Directory 안에 Directory를 넣을 수 있는것 같기는 한 것 같습니다.

 

혹시나 플러그인이 있나 먼저 살펴봤는데 예전 버전의 지원만 하는것 같습니다.

GitHub - acrobit/docusaurus-plugin-auto-sidebars: A docusaurus plugin that generates the sidebar items automatically by filesyst

 

 

추가로 공식 Documentation을 좀 더 찾아봤는데 아래와 같이 제가 원하는 복잡한 케이스에 대해서도 지원을 하는것 같습니다.

Sidebar | Docusaurus

 

이제는 저 sidebar를 제가 원하는 형태로 만들어주는 코드 작성만 하면 되겠네요.

그 부분은 docsify나 여기나 동일하고 코드 복잡도가 docusaurus가 조금 더 있는 정도의 차이일 것 같습니다.

 

그래서 예시 코드랑 결과를 확인해봤습니다.

예시 결과(왼쪽) 과 예시 사이드바 코드(오른쪽)

 

2. 검색 기능

Docusaurus - 검색기능을 지원

검색의 품질은 확인이 필요하겠지만 여러개의 옵션을 지원하는걸 보면 파트에서 사용하는 수준에는 충분해보입니다.

GitHub - easyops-cn/docusaurus-search-local: Offline/local search for Docusaurus v2/v3

 

Search의 경우 영어는 잘 작동하는것으로 확인되었습니다.

디자인도 그렇고 맘에 드네요 ㅎㅎ

다만 한글로 검색은 안되는것 같습니다.

해당 플러그인은 한글은 지원하지 않습니다.

MihaiValentin/lunr-languages: A collection of languages stemmers and stopwords for Lunr Javascript library (github.com)

GitHub - MihaiValentin/lunr-languages: A collection of languages stemmers and stopwords for Lunr Javascript library

위의 플러그인은 lunr-languages를 쓴다고 하고 여기서 지원하는 언어는 플러그인에서 사용할 수 있다고합니다.

다행히 한국어도 있는데, 바로 적용안되는것을 봐서는 추가적인 세팅이 필요한것 같습니다.

lunr 언어 지원

 

3. PDF export 기능 (Userguide, SRS 를 위해서 필요합니다.)

자체적으로는 지원하지 않는것으로 보이고 여러 오픈소스나 플러그인을 확인해봤습니다.

Generate PDF handbook with Docusaurus using GitHub Actions

mr-pdf

GitHub - nuxnik/docusaurus-wkhtmltopdf: Docusaurus PDF Generator

 

위의 플러그인들은 docusaurus 개발 속도가 빨라서 (현재 3.4.0)  pdf export (플러그인은 v1,v2만 지원) 기능이 아주 잘 되어있지는 않은것으로 보입니다.

 

조금 더 찾아보니 다른 PDF 변환 플러그인이 있었습니다.

이들은 작동은 하는데 몇가지 처리를 해줘야할 것 같습니다. 

확인 작업이 추가로 필요합니다.

 

GitHub - signcl/docusaurus-prince-pdf: Docusaurus PDF generator using Prince XML

GitHub - jean-humann/docs-to-pdf: Generate PDF for document website 🧑‍🔧

 

 

4. 버전별 문서 관리 기능

다만 이 버전 관리를 위해서 디렉토리 구조나 코드 작성이 많이 필요한지는 추가적으로 확인이 필요합니다.

그래서 아래 가이드를 보고 코드 작성을 통해서 시도해봤습니다.

 

Versioning | Docusaurus

버저닝을 위해 해야하는 작업

1. version폴더를 따로 만들고 해당 폴더로 문서들을 옮겨줌 : versioned_docs/version-{버전}

2. version별 sidebar 파일이 특정 위치에 필요함 : versioned_sidebars/version-{버전}-sidebars.json

json 파일의 형식은 아래와 같아야합니다. 

{
  "sidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}

그리고 Root 프로젝트(current version)의 sidebars파일은 sidebars.ts로 동일합니다.

 

3. versions.json 파일에 {버전}을 추가

아래와 같이 버전명을 추가해줍니다.

[
  "2.0.0",
  "1.9.0",
]

 

4. UI에 version navbar 추가

docusaurus.config.ts의 themeConfig의 Item 배열에 아래 내용을 추가합니다.

themeConfig: {
	  ...,
      items: [
      	...,
        {
          type: 'docsVersionDropdown',
          position: 'right',
          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
          dropdownActiveClassDisabled: true,
        },
      ],
      ...
}

 

아직은 완전히 잘 쓴것은 아니지만
버전별로 문서들이 달리 뜨는것을 확인했기에 이정도면 충분히 쓸 수 있다고 생각했습니다.

버전별로 다른 출력 Next버전 (왼쪽), 1.0.0버전 (오른쪽)

 

 

5. Github pages로 배포가 가능 해야함.

Docusaurus - Github Actions를 지원

이 정도로만 지원해주면 제가 Deploy에 원하는 모든 기능은 할 수 있을것으로 생각됩니다.

 

6. mermaid를 지원 해야함.

Docusaurus - mermaid 기본 plugin으로 지원

마찬가지로 mermaid 코드를 chart로 출력만 하면 되기 때문에 플러그인만 있으면 문제는 없을것 같습니다.

아래와 같이 docusaurus.config.ts 파일에 mermaid 테마와 markdown 설정을 추가합니다.

 themes: [
    // ... Your other themes.
    '@docusaurus/theme-mermaid',
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
      ({
        // ... Your options.
        // `hashed` is recommended as long-term-cache of index file is possible.
        hashed: true,
        // For Docs using Chinese, The `language` is recommended to set to:
        // ```
        // language: ["en", "zh"],
        // ```
      }),
    ],

  ],
  markdown: {
    mermaid: true,
  },

그러면 아래와 같이 mermaid가 작동하게됩니다.

mermaid 동작하는 예시

 

7. 다크모드

(저와 리더님이 원합니다 ㅎ.. 흰색은 눈아파요)

Docusaurus - 다크모드 지원

다크모드 지원은 아주 좋습니다 ㅎ 

 

8. 코드블럭 하이라이팅

플러그인도 있으나 Docusaurus는 기본기능으로 markdown의 codeblock을 지원합니다.

Code blocks | Docusaurus

또한 Golang과 CPP을 기본으로 지원하여 우리의 프로젝트에서는 너무 좋은 사용성이 될 것 같습니다.

Codeblock에서 Golang을 지원합니다.

 

 

Docusaurus의 마크다운 내 텍스트 제약사항

테스트를 해보다가 몇 가지 제약사항이 있어 이를 추가해둡니다.

 

1.<> 같은 특수문자는 오류를 발생시킵니다.

- task 설치: <https://taskfile.dev>

       | timedate   | string <date-time> , The datetime of the system    |

2. {} 같은 특수문자는 출력이 불가능합니다.

  - status : {OK, Failed}, state: {initialized, uninitialized, ...}

 

이런 문자열들을 []로 변경하면 오류가 없어집니다.

3. 링크 관련된 오류가 있으면 빌드 오류가 날 수 있습니다.

이 부분은 정확한지는 모르겠으나 

Markdown 내에 link로 다른 사이트를 링크하는게 있으면 문제가 생기는데 정확한 원인은 검색이 필요할거같습니다.

 

조금 더 확인 해 봤을때

docusaurus.config.ts 내의 아래 부분을 ignore로 변경해주면 빌드가 가능한것 같습니다.

 onBrokenLinks: 'ignore',
 onBrokenMarkdownLinks: 'ignore',

 

4. API doc 형태의 것들이 문제를 일으킵니다.

GET device/{serial}

{} 이게 문제를 일으킵니다..

 

이 제약 사항들을 수정하고 문제없이 빌드되게 만드는 작업이 좀 쉽지 않고 시간이 좀 걸릴것으로 생각됩니다.