문서
테마 설정

테마 설정

테마는 theme.config.jsx 파일로 구성됩니다. 이 파일은 구성을 포함하는 객체를 내보내야 합니다. 예를 들면:

theme.config.jsx
export default {
  project: {
    link: "https://github.com/shuding/nextra",
  },
  logo: <b>Project</b>,
};

각 옵션에 대한 자세한 정보는 아래에 나열되어 있습니다.

전역

문서 저장소

문서의 저장소 URL을 설정합니다. 이는 "이 페이지 수정하기" 링크와 "피드백" 링크를 생성하는 데 사용됩니다.

OptionTypeDescription
docsRepositoryBasestring문서 저장소의 URL.

경로 지정

문서가 모노레포, 하위 폴더 또는 저장소의 다른 브랜치 안에 있는 경우, docsRepositoryBase를 문서의 pages/ 폴더의 루트 경로로 간단히 설정할 수 있습니다. 예를 들어:

export default {
  docsRepositoryBase: "https://github.com/shuding/nextra/tree/main/docs",
};

그러면 Nextra가 자동으로 모든 페이지에 대한 올바른 파일 경로를 생성합니다.

SEO 옵션

useNextSeoProps 옵션을 통해 SEO 관련 설정을 구성할 수 있습니다. useNextSeoProps 함수는 Next SEO (opens in a new tab) 컴포넌트에 전달될 props를 반환합니다.

이것은 또한 훅이므로, 값을 조건부로 반환하기 위해 내부에서 useRouter와 같은 API를 사용할 수 있습니다.

OptionTypeDescription
useNextSeoProps() => NextSeoPropsNext SEO에 대한 옵션을 반환하는 React 훅 함수.

예를 들어, 모든 페이지에서 <title>에 동일한 접미사를 렌더링할 수 있습니다:

제목 접미사
export default {
  useNextSeoProps() {
    return {
      titleTemplate: "%s – SWR",
    };
  },
};

%s는 페이지 제목으로 대체될 플레이스 홀더 (opens in a new tab)입니다.

홈페이지에 접미사를 추가하지 않도록 조건부로 반환할 수도 있습니다:

import { useRouter } from "next/router";
 
export default {
  useNextSeoProps() {
    const { asPath } = useRouter();
    if (asPath !== "/") {
      return {
        titleTemplate: "%s – SWR",
      };
    }
  },
};

헤드 태그

웹사이트의 <head> 태그를 구성합니다. 메타 태그, 제목, 파비콘 등을 추가할 수 있습니다.

OptionTypeDescription
headReact.ReactNode | React.FC<head> 내용을 렌더링하는 컴포넌트.

정적 헤드 태그

정적 헤드 태그만 있는 경우, head에 직접 넣는 것이 쉽습니다. 예를 들어:

export default {
  head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta property="og:title" content="Nextra" />
      <meta property="og:description" content="The next site builder" />
    </>
  ),
};

페이지 기반 동적 태그

현재 페이지의 프론트매터를 기반으로 헤드 태그를 동적으로 생성하기 위해 head함수 컴포넌트로 사용할 수도 있습니다. 예를 들어:

import { useRouter } from "next/router";
import { useConfig } from "nextra-theme-docs";
 
export default {
  head: () => {
    const { asPath, defaultLocale, locale } = useRouter();
    const { frontMatter } = useConfig();
    const url =
      "https://my-app.com" +
      (defaultLocale === locale ? asPath : `/${locale}${asPath}`);
 
    return (
      <>
        <meta property="og:url" content={url} />
        <meta property="og:title" content={frontMatter.title || "Nextra"} />
        <meta
          property="og:description"
          content={frontMatter.description || "The next site builder"}
        />
      </>
    );
  },
};

useConfig 훅과 frontMatter 객체에 대한 자세한 정보는 useConfig API 섹션을 참조할 수 있습니다.

다크 모드와 테마

웹사이트의 테마 동작을 사용자 정의합니다.

OptionTypeDescription
darkModeboolean다크 모드 토글 버튼을 표시하거나 숨깁니다.
nextThemesobjectConfiguration for the next-themes (opens in a new tab) 패키지에 대한 구성.

테마 색상

라이트 및 다크 테마에 대한 기본 색조와 채도 값을 설정하여 웹사이트의 테마 색상을 조정할 수 있습니다.

OptionTypeDescription
primaryHuenumber | { dark: number; light: number }기본 테마 색상의 색조.
primarySaturationnumber | { dark: number; light: number }기본 테마 색상의 채도.

이 웹사이트에서 직접 시도해보세요:

색조채도

내비게이션 바

로고

내비게이션 바에 렌더링되는 웹사이트의 로고. React 노드나 함수 컴포넌트일 수 있습니다.

OptionTypeDescription
logoReact.ReactNode | React.FC웹사이트의 로고.
logoLinkboolean | string로고의 링크.
사용자 정의 로고
export default {
  logo: (
    <>
      <svg width="24" height="24" viewBox="0 0 24 24">
        <path
          fill="currentColor"
          d="M14.683 14.828a4.055 4.055 0 0 1-1.272.858a4.002 4.002 0 0 1-4.875-1.45l-1.658 1.119a6.063 6.063 0 0 0 1.621 1.62a5.963 5.963 0 0 0 2.148.903a6.035 6.035 0 0 0 3.542-.35a6.048 6.048 0 0 0 1.907-1.284c.272-.271.52-.571.734-.889l-1.658-1.119a4.147 4.147 0 0 1-.489.592z M12 2C6.486 2 2 6.486 2 12s4.486 10 10 10s10-4.486 10-10S17.514 2 12 2zm0 2c2.953 0 5.531 1.613 6.918 4H5.082C6.469 5.613 9.047 4 12 4zm0 16c-4.411 0-8-3.589-8-8c0-.691.098-1.359.264-2H5v1a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2h2a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2v-1h.736c.166.641.264 1.309.264 2c0 4.411-3.589 8-8 8z"
        />
      </svg>
      <span style={{ marginLeft: ".4em", fontWeight: 800 }}>
        My Cool Project
      </span>
    </>
  ),
};

프로젝트 링크

내비게이션 바에 프로젝트의 홈페이지로 연결되는 버튼을 표시합니다. 기본적으로 Nextra의 GitHub 저장소로 연결됩니다.

OptionTypeDescription
project.linkstring프로젝트 홈페이지의 URL.
project.iconReact.ReactNode | React.FC프로젝트 링크의 아이콘 또는 요소.

project.linkproject.icon을 구성하여 프로젝트 링크를 사용자 정의할 수 있습니다. 예를 들어 GitLab 저장소로 연결하도록 만들 수 있습니다:

프로젝트 링크
export default {
  project: {
    link: "https://gitlab.com/inkscape/inkscape",
    icon: (
      <svg width="24" height="24" viewBox="0 0 256 256">
        <path
          fill="currentColor"
          d="m231.9 169.8l-94.8 65.6a15.7 15.7 0 0 1-18.2 0l-94.8-65.6a16.1 16.1 0 0 1-6.4-17.3L45 50a12 12 0 0 1 22.9-1.1L88.5 104h79l20.6-55.1A12 12 0 0 1 211 50l27.3 102.5a16.1 16.1 0 0 1-6.4 17.3Z"
        ></path>
      </svg>
    ),
  },
};

icon이 없으면 기본적으로 GitHub 아이콘 (opens in a new tab)이 됩니다.

채팅 링크

내비게이션 바에 프로젝트의 포럼이나 다른 소셜 미디어로 연결되는 버튼을 표시합니다.

OptionTypeDescription
chat.linkstring채팅 링크의 URL.
chat.iconReact.ReactNode | React.FC채팅 링크의 아이콘 또는 요소.

chat.linkchat.icon을 구성하여 채팅 링크를 사용자 정의할 수 있습니다. 예를 들어 Twitter 계정으로 연결하도록 만들 수 있습니다:

export default {
  chat: {
    link: "https://twitter.com/shuding_",
    icon: (
      <svg width="24" height="24" viewBox="0 0 248 204">
        <path
          fill="currentColor"
          d="M221.95 51.29c.15 2.17.15 4.34.15 6.53 0 66.73-50.8 143.69-143.69 143.69v-.04c-27.44.04-54.31-7.82-77.41-22.64 3.99.48 8 .72 12.02.73 22.74.02 44.83-7.61 62.72-21.66-21.61-.41-40.56-14.5-47.18-35.07a50.338 50.338 0 0 0 22.8-.87C27.8 117.2 10.85 96.5 10.85 72.46v-.64a50.18 50.18 0 0 0 22.92 6.32C11.58 63.31 4.74 33.79 18.14 10.71a143.333 143.333 0 0 0 104.08 52.76 50.532 50.532 0 0 1 14.61-48.25c20.34-19.12 52.33-18.14 71.45 2.19 11.31-2.23 22.15-6.38 32.07-12.26a50.69 50.69 0 0 1-22.2 27.93c10.01-1.18 19.79-3.86 29-7.95a102.594 102.594 0 0 1-25.2 26.16z"
        />
      </svg>
    ),
  },
};

icon이 없으면 기본적으로 Discord 아이콘이 됩니다.

메뉴 및 사용자 정의 링크

내비게이션 바에 사용자 정의 메뉴나 링크를 추가하는 방법은 페이지 구성을 확인하세요.

검색

OptionTypeDescription
search.componentReact.ReactNode | React.FC<{ className?: string directories: Item[] }>
search.emptyResultReact.ReactNode | React.FC결과 없음 텍스트
search.loadingReact.ReactNode | React.FC로딩 텍스트
search.errorstring | (() => string)오류 텍스트
search.placeholderstring | (() => string)플레이스홀더 텍스트

배너

웹사이트 상단에 배너를 표시합니다. 경고나 공지를 표시하는 데 사용할 수 있습니다.

OptionTypeDescription
banner.dismissibleboolean닫을 수 있는 배너인지 여부.
banner.keystring배너 상태(닫힘 여부)를 유지하기 위한 저장소 키.
banner.textReact.ReactNode | React.FC배너의 텍스트.

배너 키

배너는 닫을 수 있습니다. 기본적으로 banner.key는 "nextra-banner"가 되며, 이는 클라이언트에서 배너 상태(닫힘 여부)를 유지하기 위해 localStorage (opens in a new tab)에서 사용됩니다.

배너 텍스트를 업데이트한 경우, 배너가 다시 표시되도록 키를 변경해야 합니다. 가장 좋은 방법은 항상 현재 텍스트에 대한 설명적인 키를 사용하는 것입니다. 예를 들어:

배너
export default {
  banner: {
    key: "2.0-release",
    text: (
      <a href="https://nextra.site" target="_blank">
        🎉 Nextra 2.0이 출시되었습니다. 자세히 알아보기 →
      </a>
    ),
  },
};

내비게이션 바 사용자 정의

전체 내비게이션 바 컴포넌트를 사용자 정의합니다.

OptionTypeDescription
navbar.componentReact.ReactNode | React.FC<NavBarProps>내비게이션 바 컴포넌트.
navbar.extraContentReact.ReactNode | React.FC마지막 아이콘 뒤에 추가 콘텐츠를 표시합니다.

사이드바

OptionTypeDescription
sidebar.defaultMenuCollapseLevelnumber왼쪽 메뉴가 기본적으로 접히는 폴더 레벨을 지정합니다. 기본값은 2입니다.
sidebar.autoCollapsebooleantrue인 경우, defaultMenuCollapseLevel 위의 비활성 폴더를 자동으로 접습니다.
sidebar.titleComponentReact.ReactNode | React.FC<{ type: string; title: string; route: string; }>사이드바 제목에 대한 사용자 정의 렌더러.
sidebar.toggleButtonboolean사이드바 토글 버튼을 숨기거나 표시합니다. 기본값은 `false`입니다.

메뉴 접기 레벨

기본적으로 사이드바 메뉴는 레벨 2에서 접힙니다. sidebar.defaultMenuCollapseLevel을 다른 숫자로 설정하여 이를 변경할 수 있습니다. 예를 들어, 1로 설정하면 모든 폴더가 기본적으로 접히고, Infinity로 설정하면 모든 중첩 폴더가 기본적으로 펼쳐집니다.

sidebar.autoCollapsetrue로 설정되면, 활성/포커스된 경로를 포함하지 않는 모든 폴더는 sidebar.defaultMenuCollapseLevel에 의해 설정된 레벨까지 자동으로 접힙니다. 예를 들어, defaultMenuCollapseLevel2이면 최상위 폴더는 자동으로 접히지 않습니다.

사이드바 콘텐츠 사용자 정의

구분자 항목과 함께 sidebar.titleComponent 옵션을 사용하여 사이드바 콘텐츠가 렌더링되는 방식을 사용자 정의할 수 있습니다:

사용자 정의 사이드바
export default {
  sidebar: {
    titleComponent({ title, type }) {
      if (type === 'separator') {
        return (
          <div style={{ background: 'cyan', textAlign: 'center' }}>{title}</div>
        )
      }
      if (title === 'About') {
        return <>❓ {title}</>
      }
      return <>👉 {title}</>
    }
  }
}

콘텐츠

MDX 컴포넌트

콘텐츠를 렌더링하기 위한 사용자 정의 MDX 컴포넌트 (opens in a new tab)를 제공합니다. 예를 들어, 코드 블록을 렌더링하기 위해 사용자 정의 pre 컴포넌트를 사용할 수 있습니다.

OptionTypeDescription
componentsRecord<string, React.FC>사용자 정의 MDX 컴포넌트.

쓰기 방향

웹사이트의 기본 쓰기 방향.

OptionTypeDescription
direction"ltr" | "rtl"기본 쓰기 방향.

메인 콘텐츠

페이지의 메인 영역 상단 및/또는 하단에 콘텐츠를 렌더링합니다. 이는 댓글 섹션, 뉴스레터 양식 또는 기타 유형의 콘텐츠를 렌더링하는 데 사용할 수 있습니다.

OptionTypeDescription
mainReact.FC<{ children: React.ReactNode }>메인 콘텐츠의 컴포넌트.

TOC 사이드바

목차

페이지 오른쪽에 목차를 표시합니다. 제목 간 탐색에 유용합니다.

OptionTypeDescription
toc.componentReact.ReactNode | React.FC<TOCProps>TOC의 사용자 정의 렌더러.
toc.extraContentReact.ReactNode | React.FCTOC 콘텐츠 아래에 추가 콘텐츠를 표시합니다.
toc.floatboolean콘텐츠 옆에 TOC를 띄웁니다.
toc.titleReact.ReactNode | React.FCTOC 사이드바의 제목. 기본값은 "On This Page"입니다.
toc.headingComponentReact.FC<{ id: string, children: string }>TOC 제목의 사용자 정의 렌더러.
toc.backToTopboolean`맨 위로 스크롤` 링크를 추가합니다.

플로팅 TOC

toc.float는 기본적으로 활성화되어 있습니다. 활성화되면 TOC가 페이지 오른쪽에 표시되고 스크롤 시 고정됩니다. 비활성화되면 TOC가 페이지 사이드바에 직접 표시됩니다.

편집 링크

GitHub(또는 다른 곳)의 파일 URL을 가리키는 "이 페이지 편집하기" 링크를 페이지에 표시합니다.

OptionTypeDescription
editLink.textReact.ReactNode | React.FC기본 편집 링크의 내용.
editLink.componentReact.FC<{ children: React.ReactNode className?: string filePath?: string }> | null사용자 정의 편집 링크 컴포넌트.

비활성화하려면 editLink.componentnull로 설정할 수 있습니다.

피드백 링크

내장된 피드백 링크는 사용자가 문서에 대한 피드백을 제출할 수 있는 방법을 제공합니다. 기본적으로 현재 웹사이트 제목이 미리 채워진 문서 저장소의 이슈 생성 양식을 가리키는 링크입니다: 예시 (opens in a new tab).

OptionTypeDescription
feedback.contentReact.ReactNode | React.FC피드백 버튼의 내용.
feedback.labelsstring새로 생성된 GitHub 이슈에 추가할 수 있는 라벨.
feedback.useLink() => string사용자 정의 링크, 기본적으로 `docsRepositoryBase`에 설정된 저장소에 이슈를 열 것입니다.

비활성화하려면 feedback.contentnull로 설정할 수 있습니다.

페이지 하단

내비게이션

콘텐츠 하단에 이전 페이지와 다음 페이지 링크를 표시합니다. 페이지 간 탐색에 유용합니다.

OptionTypeDescription
navigationboolean | object내비게이션 링크를 활성화하거나 비활성화합니다.
navigation.prevboolean이전 페이지 링크를 활성화하거나 비활성화합니다.
navigation.nextboolean다음 페이지 링크를 활성화하거나 비활성화합니다.
내비게이션
export default {
  navigation: {
    prev: true,
    next: true,
  },
};

위의 설정은 navigation: true와 동일합니다.

마지막 업데이트 날짜

각 페이지의 마지막 업데이트 날짜를 표시합니다. 콘텐츠의 최신성을 보여주는 데 유용합니다.

OptionTypeDescription
gitTimestampReact.ReactNode | React.FC<{ timestamp: Date }>마지막 업데이트 정보를 렌더링하는 컴포넌트.

푸터

웹사이트의 푸터 영역입니다. 기본 푸터에 일부 콘텐츠를 지정하거나 사용자 정의 컴포넌트로 완전히 사용자 정의할 수 있습니다.

OptionTypeDescription
footer.textReact.ReactNode | React.FC기본 푸터 컴포넌트의 콘텐츠.
footer.componentReact.ReactNode | React.FC<{ menu: boolean }>사용자 정의 푸터 컴포넌트.

저작권 정보

기본 푸터에 저작권 정보와 같은 간단한 콘텐츠를 추가할 수 있습니다:

export default {
  footer: {
    text: (
      <span>
        MIT {new Date().getFullYear()} ©{" "}
        <a href="https://nextra.site" target="_blank">
          Nextra
        </a>
        .
      </span>
    ),
  },
};

테마 전환

OptionTypeDescription
themeSwitch.componentReact.ReactNode | React.FC<{ lite?: boolean, className?: string }>테마 전환을 렌더링하는 컴포넌트.
themeSwitch.useOptionsThemeOptions | () => ThemeOptions테마 전환의 옵션.

옵션

지역화나 다른 목적으로 옵션 이름을 사용자 정의할 수 있습니다:

export default {
  themeSwitch: {
    useOptions() {
      return {
        light: "라이트",
        dark: "다크",
        system: "시스템",
      };
    },
  },
};

오류 페이지

404 - 찾을 수 없음

500 - 내부 서버 오류

파비콘 글리프 (실험적)

이는 모든 브라우저에서 지원되지 않지만, 이모지나 문자를 사용하여 웹사이트의 파비콘을 간단히 사용자 정의하는 좋은 방법입니다.

OptionTypeDescription
faviconGlyphstring파비콘으로 사용할 글리프.