Docusaurus Sidebar 제목에 prefix Icon 추가하기

Docusaurus 문서화를 하던 와중에 페이지의 직관성 및 가독성이 더 필요하다고 느끼게 되었습니다.

그런 이유로 일부 기능을 더 보강하려고 합니다.

그래서 가장 처음에 생각난 기능이 바로 Sidebar의 prefix에 icon을 추가해서 직관적으로 문서와 카테고리를 분류 하는 것입니다.

 

1. Custom CSS 추가 및 반영

우선은 custom.css 파일을 적용하기 위해서

아래와 같이 docusaurus.config.ts (혹은 js)에 custom.css 파일을 등록해 두어야합니다.

presets: [
    [
      'classic',
      {
        docs: {
          중략...
        },
        blog: {
         중략...
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      } satisfies Preset.Options,
    ],
  ],

 

그리고 src/css/custom.css를 만들고 아래 내용을 추가합니다.

/*

  Add a custom icon for sidebar directories

 */
.icon > div::before {
  content: '';
  display: inline-block;
  margin: auto -8px auto 8px;
  width: 20px;
  height: 20px;
}

.directory-icon > div::before {
  background: url('/static/img/directory.png');
  background-size: contain;
  background-repeat: no-repeat;
  background-position: center;
}
/*

  Add a custom icon for sidebar documents

*/
.icon > a::before {
  content: '';
  display: inline-block;
  margin: auto 0px auto 8px;
  width: 20px;
  height: 20px;
}
.document-icon > a::before {
  background: url('/static/img/document.png');
  background-size: contain;
  background-repeat: no-repeat;
  background-position: center;
}

 

2. 원하는 아이콘을 다운받고 추가하기

원하는 아이콘 이미지를 /static/img/ 하위에 추가합니다.

예시의 경우 /static/img/document.png , /static/img/directory.png를 추가했습니다.

 

3. Sidebar Entry 정보에 className 추가

그리고 sidebar 파일의 각 entry 정보에 className을 추가해야 합니다.

Category type에 className으로 "icon directory-icon"을 추가하고

Doc type에 className으로 "icon document-icon"을 추가합니다.

예시는 아래와 같습니다.

 

sidebar.json

[
  {
    "type": "doc",
    "id": "adr-architecture/intro",
    "className": "icon document-icon"
  },
  {
    "type": "category",
    "label": "Github-Review-Dashboard-and-Alarm-Bot",
    "className": "icon directory-icon",
    "items": [
      {
        "type": "doc",
        "id": "adr-architecture/Github-Review-Dashboard-and-Alarm-Bot/README",
        "className": "icon document-icon"
      },
      {
        "type": "category",
        "label": "db_deploy",
        "className": "icon directory-icon",
        "items": [
          {
            "type": "doc",
            "id": "adr-architecture/Github-Review-Dashboard-and-Alarm-Bot/db_deploy/README",
            "className": "icon document-icon"
          }
        ]
      },
      {
        "type": "category",
        "label": "frontend",
        "className": "icon directory-icon",
        "items": [
          {
            "type": "doc",
            "id": "adr-architecture/Github-Review-Dashboard-and-Alarm-Bot/frontend/README",
            "className": "icon document-icon"
          }
        ]
      }
    ]
  },
  {
    "type": "category",
    "label": "packer-qemu-template",
    "className": "icon directory-icon",
    "items": [
      {
        "type": "doc",
        "id": "adr-architecture/packer-qemu-template/README",
        "className": "icon document-icon"
      }
    ]
  },
  {
    "type": "category",
    "label": "tutorial-basics",
    "className": "icon directory-icon",
    "items": [
      {
        "type": "doc",
        "id": "adr-architecture/tutorial-basics/congratulations",
        "className": "icon document-icon"
      },
      {
        "type": "doc",
        "id": "adr-architecture/tutorial-basics/create-a-blog-post",
        "className": "icon document-icon"
      },
      {
        "type": "doc",
        "id": "adr-architecture/tutorial-basics/create-a-document",
        "className": "icon document-icon"
      },
      {
        "type": "doc",
        "id": "adr-architecture/tutorial-basics/create-a-page",
        "className": "icon document-icon"
      },
      {
        "type": "doc",
        "id": "adr-architecture/tutorial-basics/deploy-your-site",
        "className": "icon document-icon"
      }
    ]
  },
  {
    "type": "category",
    "label": "tutorial-extras",
    "className": "icon directory-icon",
    "items": [
      {
        "type": "doc",
        "id": "adr-architecture/tutorial-extras/manage-docs-versions",
        "className": "icon document-icon"
      },
      {
        "type": "doc",
        "id": "adr-architecture/tutorial-extras/translate-your-site",
        "className": "icon document-icon"
      }
    ]
  }
]

위의 작업이 완료되면 사이드바에 icon 추가 작업을 완료 한 것입니다.

서버 실행

npm run start로 실제 반영된 모습을 아래와 같이 확인 할 수 있습니다.

Sidebar의 entry 앞에 directory와 document 이미지가 반영된 모습

 

실제 코드는 아래 링크에서 확인해 볼 수 있습니다.

GitHub - ray5273/docusaurus-template: docusaurus-template

 

그리고 예시 웹 사이트도 아래 링크를 통해 접속할 수 있습니다.

https://ray5273.github.io/docusaurus-template/adr-architecture/intro

Tutorial Intro | Docusaurus Template

 

 

참고자료

https://tils.pariskwsto.com/docusaurus/sidebar-icons

Sidebar Icons | TILs