스타일과 레이아웃

팁

스타일시트를 사용한 스타일 지정 방법을 설명합니다. For more advanced customizations (DOM structure, React code...), refer to the swizzling guide.

도큐사우루스 사이트는 단일 페이지 리액트 애플리케이션입니다. 여러분은 리액트 앱에 스타일을 적용하는 것처럼 도큐사우루스 사이트의 스타일을 지정할 수 있습니다.

기본 설정과 만들고자 하는 웹 사이트 유형에 따라 몇 가지 접근 방식과 프레임워크가 있습니다. 사용자와 상호 작용이 필요하고 웹 앱처럼 동작하는 웹 사이트는 스타일 설정을 컴포넌트와 함께 배치하는 현대적인 스타일 접근 방식을 활용할 수 있습니다. 컴포넌트에 스타일을 적용하는 방식은 컴포넌트를 수정하거나 다른 컴포넌트로 대체하는 경우 특히 유용합니다.

Global styles

이 방식은 대부분의 개발자(프론트엔드 개발자가 아니더라도)에게 가장 익숙한 전통적인 스타일 적용 방식입니다. 사용자 정의가 많지 않은 소규모 웹사이트에서는 잘 작동합니다.

If you're using @docusaurus/preset-classic, you can create your own CSS files (e.g. /src/css/custom.css) and import them globally by passing them as an option of the classic theme.

docusaurus.config.js

export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};

작성한 CSS는 사이트 전체에 반영되며 문자열 리터럴을 사용해 직접 참조할 수 있습니다.

/src/css/custom.css

.purple-text {
  color: rebeccapurple;
}

function MyComponent() {
  return (
    <main>
      <h1 className="purple-text">Purple Heading!</h1>
    </main>
  );
}

요소에 CSS를 추가하려면 브라우저에서 개발도구를 열어 해당 클래스 이름을 확인할 수 있습니다. 클래스 이름에는 여러 종류가 있습니다.

• Theme class names. These class names are listed exhaustively in the next subsection. 기본 속성은 가지고 있지는 않습니다. 사용자 정의 CSS에서 안정된 클래스 이름을 대상으로 항상 우선 순위를 지정해야 합니다.
• Infima class names. These class names are found in the classic theme and usually follow the BEM convention of block__element--modifier. 대부분의 경우 안정적이지만 여전히 구현 세부 사항으로 간주되므로 별도로 대상을 지정하지 않아야 합니다. However, you can modify Infima CSS variables.
• CSS module class names. These class names end with a hash which may change over time (codeBlockContainer_RIuc). 구현 세부 사항으로 간주되며 거의 대부분 사용자 정의 CSS에서 대상을 지정하지 않아야 합니다. If you must, you can use an attribute selector ([class*='codeBlockContainer']) that ignores the hash.

Theme Class Names

강력하고 유지관리할 수 있는 전역 레이아웃 스타일을 위해 몇 가지 안정적인 CSS 클래스 이름을 제공합니다. 각 이름은 테마에 종속되지 않으며 사용자 정의 CSS 대상이 됩니다.

팁

If you can't find a way to create a robust CSS selector, please report your customization use-case and we will consider adding new class names.

Exhaustive list of stable class names

export const ThemeClassNames = {
  page: {
    blogListPage: 'blog-list-page',
    blogPostPage: 'blog-post-page',
    blogTagsListPage: 'blog-tags-list-page',
    blogTagPostListPage: 'blog-tags-post-list-page',
    blogAuthorsListPage: 'blog-authors-list-page',
    blogAuthorsPostsPage: 'blog-authors-posts-page',
    docsDocPage: 'docs-doc-page',
    docsTagsListPage: 'docs-tags-list-page',
    docsTagDocListPage: 'docs-tags-doc-list-page',
    mdxPage: 'mdx-page',
  },
  wrapper: {
    main: 'main-wrapper', 
    blogPages: 'blog-wrapper',
    docsPages: 'docs-wrapper',
    mdxPages: 'mdx-wrapper',
  },
  common: {
    editThisPage: 'theme-edit-this-page',
    lastUpdated: 'theme-last-updated',
    backToTopButton: 'theme-back-to-top-button',
    codeBlock: 'theme-code-block',
    admonition: 'theme-admonition',
    unlistedBanner: 'theme-unlisted-banner',
    draftBanner: 'theme-draft-banner',
    admonitionType: (type: string) => `theme-admonition-${type}`,
  },
  announcementBar: {
    container: 'theme-announcement-bar',
  },
  layout: {
    navbar: {
      container: 'theme-layout-navbar',
      containerLeft: 'theme-layout-navbar-left',
      containerRight: 'theme-layout-navbar-right',
      mobileSidebar: {
        container: 'theme-layout-navbar-sidebar',
        panel: 'theme-layout-navbar-sidebar-panel',
      },
    },
    main: {
      container: 'theme-layout-main',
    },
    footer: {
      container: 'theme-layout-footer',
      column: 'theme-layout-footer-column',
    },
  },
  docs: {
    docVersionBanner: 'theme-doc-version-banner',
    docVersionBadge: 'theme-doc-version-badge',
    docBreadcrumbs: 'theme-doc-breadcrumbs',
    docMarkdown: 'theme-doc-markdown',
    docTocMobile: 'theme-doc-toc-mobile',
    docTocDesktop: 'theme-doc-toc-desktop',
    docFooter: 'theme-doc-footer',
    docFooterTagsRow: 'theme-doc-footer-tags-row',
    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
    docSidebarContainer: 'theme-doc-sidebar-container',
    docSidebarMenu: 'theme-doc-sidebar-menu',
    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
    docSidebarItemLink: 'theme-doc-sidebar-item-link',
    docSidebarItemCategoryLevel: (level: number) =>
      `theme-doc-sidebar-item-category-level-${level}` as const,
    docSidebarItemLinkLevel: (level: number) =>
      `theme-doc-sidebar-item-link-level-${level}` as const,
  },
  blog: {
    blogFooterTagsRow: 'theme-blog-footer-tags-row',
    blogFooterEditMetaRow: 'theme-blog-footer-edit-meta-row',
  },
  pages: {
    pageFooterEditMetaRow: 'theme-pages-footer-edit-meta-row',
  },
} as const;

Styling your site with Infima

@docusaurus/preset-classic uses Infima as the underlying styling framework. 인피마는 콘텐츠 중심 웹 사이트(블로그, 문서, 랜딩 페이지)에 적합한 유연한 레이아웃과 공통 UI 구성 요소에 대한 스타일을 지원합니다. For more details, check out the Infima website.

When you scaffold your Docusaurus project with create-docusaurus, the website will be generated with basic Infima stylesheets and default styling. 인피마 CSS 변수를 전역으로 재정의할 수 있습니다.

/src/css/custom.css

:root {
  --ifm-color-primary: #25c2a0;
  --ifm-code-font-size: 95%;
}

인피마에서는 각 색상에 7가지 음영 단계를 적용합니다. We recommend using ColorBox to find the different shades of colors for your chosen primary color.

Alternatively, use the following tool to generate the different shades for your website and copy the variables into /src/css/custom.css.

팁

가독성을 위한 기본 색상에 대해 최소한 WCAG AA 레벨 명암비를 목표로 합니다. 도큐사우르스 웹사이트 자체를 사용해 색상 팔레트가 어떻게 보일지 미리 확인합니다. 일반적으로 하나의 색상이 밝은 모드와 어두운 모드에서 모두 작동하지 않기 때문에 어두운 모드에서 대체 팔레트를 사용할 수 있습니다.

기본 색상

배경:

CSS 변수 이름	Hex	색상 보정	색상 대비
--ifm-color-primary-lightest	#3cad6e		Fail 🔴
--ifm-color-primary-lighter	#359962		Fail 🔴
--ifm-color-primary-light	#33925d		Fail 🔴
--ifm-color-primary	#2e8555	0	AA 👍
--ifm-color-primary-dark	#29784c		AA 👍
--ifm-color-primary-darker	#277148		AA 👍
--ifm-color-primary-darkest	#205d3b		AAA 🏅

src/css/custom.css의 변수를 새로운 변수로 바꿉니다.

/src/css/custom.css

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

Dark Mode

In light mode, the <html> element has a data-theme="light" attribute; in dark mode, it's data-theme="dark". Therefore, you can scope your CSS to dark-mode-only by targeting html with a specific attribute.

/* 전역 인피마 변수를 덮어씀 */
[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
}
/* 하나의 클래스만 어두운 모드로 설정 */
[data-theme='dark'] .purple-text {
  color: plum;
}

팁

It is possible to initialize the Docusaurus theme directly from a docusaurus-theme query string parameter.

예시:

/docs/?docusaurus-theme=dark

/docs/configuration?docusaurus-theme=light

Data Attributes

It is possible to inject <html> data attributes with query string parameters following the docusaurus-data-<key> pattern. This gives you the flexibility to style a page differently based on the query string.

For example, let's render one of our pages with a red border and no navbar:

/src/css/custom.css

html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border

Iframe Mode

If you plan to embed some Docusaurus pages on another site though an iframe, it can be useful to create an alternative display mode and use iframe urls such as https://mysite.com/docs/myDoc?docusaurus-data-mode=iframe. It is your responsibility to provide the additional styles and decide which UI elements you want to keep or hide.

Mobile View

Docusaurus uses 996px as the cutoff between mobile screen width and desktop. 모바일 보기에서 레이아웃을 다르게 하려면 미디어 쿼리를 사용할 수 있습니다.

.banner {
  padding: 4rem;
}
/** 모바일 보기에서 padding 변경 */
@media screen and (max-width: 996px) {
  .heroBanner {
    padding: 2rem;
  }
}

Customizing the breakpoint

Some React components, such as the header and the sidebar, implement different JavaScript logic when in mobile view. If you change the breakpoint value in your custom CSS, you probably also want to update the invocations of the useWindowSize hook by swizzling the components it's used in and passing an explicit option argument.

CSS modules

To style your components using CSS Modules, name your stylesheet files with the .module.css suffix (e.g. welcome.module.css). 웹팩에서는 해당 확장자로 설정한 CSS 파일을 로드하고 여러분은 가져온 CSS 모듈의 속성으로 클래스 이름(일반 문자열을 사용하지 않고)을 참조해야 합니다. This is similar to the convention used in Create React App.

styles.module.css

.main {
  padding: 12px;
}

.heading {
  font-weight: bold;
}

.contents {
  color: #ccc;
}

import styles from './styles.module.css';

function MyComponent() {
  return (
    <main className={styles.main}>
      <h1 className={styles.heading}>Hello!</h1>
      <article className={styles.contents}>Lorem Ipsum</article>
    </main>
  );
}

클래스 이름은 웹팩에서 빌드 시 전역에서 유일한 클래스 이름으로 처리됩니다.

CSS-in-JS

경고

CSS-in-JS 지원은 진행중인 작업이므로 MUI와 같은 라이브러리에서 표시 문제가 있을 수 있습니다. Welcoming PRs.

Sass/SCSS

To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus plugin docusaurus-plugin-sass. 해당 플러그인은 전역 스타일이나 CSS 모듈 접근 모두 잘 동작합니다.

1. Install docusaurus-plugin-sass:

npm

npm install --save docusaurus-plugin-sass sass

Yarn

yarn add docusaurus-plugin-sass sass

pnpm

pnpm add docusaurus-plugin-sass sass

Bun

bun add docusaurus-plugin-sass sass

2. Include the plugin in your docusaurus.config.js file:

docusaurus.config.js

export default {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};

3. Sass/SCSS에서 스타일시트를 작성하고 가져옵니다.

Global styles using Sass/SCSS

You can now set the customCss property of @docusaurus/preset-classic to point to your Sass/SCSS file:

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        theme: {
          customCss: ['./src/css/custom.scss'],
        },
        // ...
      },
    ],
  ],
};

Modules using Sass/SCSS

Name your stylesheet files with the .module.scss suffix (e.g. welcome.module.scss) instead of .css. Webpack will use sass-loader to preprocess your stylesheets and load them as CSS modules.

styles.module.scss

.main {
  padding: 12px;

  article {
    color: #ccc;
  }
}

import styles from './styles.module.scss';

function MyComponent() {
  return (
    <main className={styles.main}>
      <article>Lorem Ipsum</article>
    </main>
  );
}

TypeScript support

To enable TypeScript support for Sass/SCSS modules, the TypeScript configuration should be updated to add the docusaurus-plugin-sass type definitions. This can be done in the tsconfig.json file:

{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}