Docusaurus config 톺아보기 (2)

1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기 3. React 기초 훑어보고 Docusaurus 설치하기 4. Docusaurus config 톺아보기 (1)

5. Docusaurus config 톺아보기 (2)

6. Swizzle로 디자인 커스터마이징하기 7. Github Pages로 Docusaurus 웹사이트 호스팅하기 8. 구글 서치 콘솔 등록하고 사용자 인사이트 얻기

이번 포스트에서는 docusaurus.config.js에서 설정할 수 있는 내용 중 디자인적 요소에 영향을 미치는 부분만 따로 모아두었다.

GNB 설정

Docusaurus 가이드 페이지의 GNB 메뉴 스크린샷

Docusaurus 가이드 페이지의 GNB를 보면 사이트 로고와 몇 개의 버튼으로 구성되어 있다. 이를 config 파일로 보면 아래와 같다.

themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: 'My Site',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: 'Tutorial',
          },
          {
            to: '/blog',
            label: 'Blog',
            position: 'left'
          },
          {
            href: 'https://github.com/facebook/docusaurus',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
    }),

사이트 로고와 이름

title: 'My Site',
logo: {
    alt: 'My Site Logo',
    src: 'img/logo.svg',
},

앞서 메타 데이터에 설정한 사이트 제목과는 별개로, GNB에 표시될 제목을 따로 설정할 수 있다. 로고 이미지 파일도 이미 기본값이 들어있으므로 같은 경로에 같은 파일명으로 덮어쓰기하면 쉽게 교체할 수 있다. 로고 이미지의 크기 등, 추가로 설정할 수 있는 옵션은 가이드 페이지에서 확인할 수 있다.

Docs로 가는 버튼

items: [
    {
        type: 'docSidebar',
        sidebarId: 'tutorialSidebar',
        position: 'left',
        label: 'Tutorial',
    },
    ...

docs로 구성한 콘텐츠를 가지고 있고, 목차의 첫번째 위치로 가는 버튼을 만들고 싶다면 items에 type이 docSidebar인 항목을 추가하면 된다. 여기서 sidebarId는 sidebars.js에 적은 사이드바 아이디를 말한다. docs의 왼편 사이드바 목차에 어떤 제목을 나열할지는 sidebars.js에 적어야 하는데, 이 때 사이드바를 구분짓는 적당한 이름을 하나 지어서 아이디값으로 설정해야 한다. 여기서 사용한 아이디값을 가지고 와서 해당 사이드바, 즉 해당 docs 콘텐츠로 보내주는 버튼을 만드는 셈이다. 이런 구조를 취하는 이유는 하나의 사이트에 docs가 여러개일 수 있기 때문에 docs들을 구분짓기 위함이다.

docs 문서 전체를 보기 바란다면 목차의 첫번째 위치로 이동시키는 게 맞지만, docs 안에서 특정 doc 페이지로 바로 이동하도록 만들고 싶을 수 있다. 해당 페이지를 목차의 첫번째 페이지로 할 수 없다면 type 속성을 바꿔서 해결할 수 있다.

position은 GNB의 왼편 혹은 오른편에 쏠리게 버튼을 위치시킬지를 정하는 속성이다. left 혹은 right 중에 선택할 수 있다. 버튼이 나열되는 순서는 items 필드 안에 나열되는 순서와 같다. 즉 docs 정보를 먼저 적었다면 docs 버튼이 더 왼쪽에 배치된다.

마지막으로 label은 버튼에 표기할 텍스트(버튼명)를 뜻한다.

Blog로 가는 버튼

items: [
    {
        to: '/blog',
        label: 'Blog',
        position: 'left'
    },
    ...

blog로 가는 버튼은 to 속성을 쓴다는 점에서 차이가 있다. 사실 to 속성은 blog 전용 속성은 아니고, 내 사이트의 특정 하위 경로로 보내고 싶을 때 쓰는 속성이다. blog의 메인 페이지는 /blog 경로에 위치한다.

하이퍼링크 버튼

items: [
    {
        href: 'https://github.com/facebook/docusaurus',
        label: 'GitHub',
        position: 'right',
    },
    ...

내 사이트의 하위 경로가 아니라 외부 페이지 링크로 가는 버튼을 만드려면 href 속성을 쓰면 된다. 당연히 버튼은 여러개 만들 수 있기 때문에 여러 링크로 가는 버튼을 GNB에 배치할 수 있다.

테마 변경 버튼

themeConfig:

    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({

    ... (중략) ...

      colorMode: {
        defaultMode: 'dark',
        disableSwitch: true,
      },

    })

앞서 설명한 docs, blog, 하이퍼링크 버튼은 themeConfig > navBar 속성 아래에 설정했다. Dark 테마와 Light 테마를 사용자가 선택할 수 있는 버튼은 navbar와 형제 위치에 별도의 속성으로 설정해야 한다. 자세한 가이드는 이 곳에서 볼 수 있다. 나는 dark 테마 1개만 사용할 생각이었기 때문에 default를 dark로 설정하고 테마 변경 버튼을 숨김 처리했다.

Footer 설정

/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
themeConfig: ({
  footer: {
    style: 'dark',
    links: [
      {
        title: 'Docs',
        items: [
          {
            label: 'Tutorial',
            to: '/docs/intro'
          }
        ]
      },
      {
        title: 'Community',
        items: [
          {
            label: 'Stack Overflow',
            href: 'https://stackoverflow.com/questions/tagged/docusaurus'
          },
          {
            label: 'Discord',
            href: 'https://discordapp.com/invite/docusaurus'
          },
          {
            label: 'Twitter',
            href: 'https://twitter.com/docusaurus'
          }
        ]
      },
      {
        title: 'More',
        items: [
          {
            label: 'Blog',
            to: '/blog'
          },
          {
            label: 'GitHub',
            href: 'https://github.com/facebook/docusaurus'
          }
        ]
      }
    ],
    copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`
  }
})

Footer에 들어가는 내용도 GNB에 메뉴를 배치하듯이 config에서 설정할 수 있다. Footer에는 보통 고정 안내 멘트나 기타 링크 버튼을 넣어놓는 경우가 대부분이기 때문에 위의 샘플에서 필요한 만큼을 복붙해가며 편집하는 것으로도 충분하다. 나중에 설명하게 될 Swizzle을 이용하면 좀 더 자유도 높은 커스터마이징도 가능하다.

Table of Contents

/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
themeConfig: ({
  tableOfContents: {
    minHeadingLevel: 2,
    maxHeadingLevel: 5
  }
})

지금 이 포스트에서도 볼 수 있듯이 화면 오른편에 목차를 오고 갈 수 있는 사이드바를 고정 노출시킬 수 있다. tableOfContents 속성을 사용하면 몇 레벨의 Heading을 목차에 포함시킬지를 지정할 수 있다. 나는 주로 포스트 내용 안에서는 H1을 쓰지 않고 H2부터 사용하기 때문에 min을 2로 설정했다. 다소 스크롤은 길어지더라도 Heading을 더 잘게 쪼개는 것을 좋아하기 때문에 max를 5로 지정했다.

Codeblock

Markdown의 codeblock을 사용하면 Docusaurus에서 알아서 코드 에디터 느낌이 나도록 스타일을 넣어준다. 코드 에디터 색상 설정을 하듯이 색상 조합을 바꾸고 싶거나, 지원하는 언어의 종류를 늘리려면 config에 설정을 추가해야 한다.

/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
themeConfig: ({
  prism: {
    theme: require('prism-react-renderer/themes/dracula'),
    additionalLanguages: ['bash', 'json', 'jsx']
  }
})

Docusaurus의 기본 Codeblock 색상이 별로 눈에 띄지 않는 거 같아서 가이드를 참고해서 Dracula로 색상을 변경했다.

그리고 언어 설정을 넣어도 인식이 잘 안되는 것 같아서 가이드에 링크된 기본 언어 목록을 살펴봤는데 업데이트가 덜 됐는지 page not found가 떴다. 그래서 지원 언어 목록을 확인하고 필요하겠다 싶은 언어를 모두 config에 포함시켰다.

1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기 3. React 기초 훑어보고 Docusaurus 설치하기 4. Docusaurus config 톺아보기 (1)

5. Docusaurus config 톺아보기 (2)

6. Swizzle로 디자인 커스터마이징하기 7. Github Pages로 Docusaurus 웹사이트 호스팅하기 8. 구글 서치 콘솔 등록하고 사용자 인사이트 얻기