메인 컨텐츠로 이동
Version: 2.0.0-beta.21 🚧

스타일과 레이아웃

tip

This section is focused on styling through stylesheets. For more advanced customizations (DOM structure, React code...), refer to the swizzling guide.

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

기본 설정과 만들고자 하는 웹 사이트 유형에 따라 몇 가지 접근 방식과 프레임워크가 있습니다. Websites that are highly interactive and behave more like web apps will benefit from more modern styling approaches that co-locate styles with the components. 컴포넌트에 스타일을 적용하는 방식은 컴포넌트를 수정하거나 다른 컴포넌트로 대체하는 경우 특히 유용합니다.

전역 스타일

This is the most traditional way of styling that most developers (including non-front-end developers) would be familiar with. It works fine for small websites that do not have much customization.

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
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./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>
);
}

If you want to add CSS to any element, you can open the DevTools in your browser to inspect its class names. Class names come in several kinds:

  • Theme class names. These class names are listed exhaustively in the next subsection. They don't have any default properties. You should always prioritize targeting those stable class names in your custom CSS.
  • Infima class names. These class names are found in the classic theme and usually follow the BEM convention of block__element--modifier. They are usually stable but are still considered implementation details, so you should generally avoid targeting them. However, you can modify Infima CSS variables.
  • CSS module class names. These class names have a hash in production (codeBlockContainer_RIuc) and are appended with a long file path in development. They are considered implementation details and you should almost always avoid targeting them in your custom CSS. If you must, you can use an attribute selector ([class*='codeBlockContainer']) that ignores the hash.

테마 클래스 이름

We provide some stable CSS class names for robust and maintainable global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS.

tip

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',
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',
},
layout: {
},
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: {
},
} as const;

인피마(Infima)를 사용해 사이트에 스타일 적용하기

@docusaurus/preset-classic인피마(Infima)를 기본 스타일 프레임워크로 사용합니다. 인피마는 콘텐츠 중심 웹 사이트(블로그, 문서, 랜딩 페이지)에 적합한 유연한 레이아웃과 공통 UI 구성 요소에 대한 스타일을 지원합니다. 좀 더 자세한 사항은 인피마 웹 사이트를 참고하세요.

create-docusaurus를 사용해 도큐사우루스 프로젝트의 뼈대를 만들면 웹사이트가 기본 Infima 스타일시트와 기본 스타일로 만들어집니다. 인피마 CSS 변수를 전역으로 재정의할 수 있습니다.

/src/css/custom.css
:root {
--ifm-color-primary: #25c2a0;
--ifm-code-font-size: 95%;
}

인피마에서는 각 색상에 7가지 음영 단계를 적용합니다. 여러분이 원하는 색상의 음영 단계를 선택하려고 할 때 ColorBox를 사용하면 좀 더 쉽게 색상을 선택할 수 있습니다.

아니면 다른 도구를 사용해 웹 사이트에 필요한 음영 색상을 생성하고 이를 복사해 /src/css/custom.css 파일에 직접 반영할 수 있습니다.

tip

Aim for at least WCAG-AA contrast ratio for the primary color to ensure readability. Use the Docusaurus website itself to preview how your color palette would look like. You can use alternative palettes in dark mode because one color doesn't usually work in both light and dark mode.

CSS Variable NameHexAdjustmentContrast Rating
--ifm-color-primary-lightest#3cad6eFail 🔴
--ifm-color-primary-lighter#359962Fail 🔴
--ifm-color-primary-light#33925dFail 🔴
--ifm-color-primary#2e85550AA 👍
--ifm-color-primary-dark#29784cAA 👍
--ifm-color-primary-darker#277148AA 👍
--ifm-color-primary-darkest#205d3bAAA 🏅

Replace the variables in src/css/custom.css with these new variables.

/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". 따라서 특정 속성을 가진 html을 대상으로 CSS 범위를 어두운 모드 전용으로 설정할 수 있습니다.

/* Overriding root Infima variables */
[data-theme='dark'] {
--ifm-color-primary: #4e89e8;
}
/* Styling one class specially in dark mode */
[data-theme='dark'] .purple-text {
color: plum;
}

Mobile View

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

.banner {
padding: 4rem;
}
/** In mobile view, reduce the padding */
@media screen and (max-width: 996px) {
.heroBanner {
padding: 2rem;
}
}

CSS 모듈

CSS 모듈을 사용해 스타일을 적용하려면 스타일 시트 파일명을 .module.css 확장자로 설정해야 합니다(welcome.module.css). Webpack will load such CSS files as CSS modules and you have to reference the class names as properties of the imported CSS module (as opposed to using plain strings). 리액트 앱 만들기 가이드에서 사용하는 방법과 비슷한 명명 규칙입니다.

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 작성하기

caution

CSS-in-JS support is a work in progress, so libs like MUI may have display quirks. Welcoming PRs.

Sass/SCSS

CSS 전처리를 위해 Sass/SCSS를 사용하고 싶다면 비공식 플러그인 docusaurus-plugin-sass를 설치해야 합니다. 해당 플러그인은 전역 스타일이나 CSS 모듈 접근 모두 잘 동작합니다.

  1. docusaurus-plugin-sass를 설치합니다.
npm install --save docusaurus-plugin-sass sass
  1. 플러그인 항목을 docusaurus.config.js 파일에 추가 설정합니다.
docusaurus.config.js
module.exports = {
// ...
plugins: ['docusaurus-plugin-sass'],
// ...
};
  1. Sass/SCSS에서 스타일시트를 작성하고 가져옵니다.

Sass/SCSS을 사용해 전역 스타일 설정하기

@docusaurus/preset-classiccustomCss 속성에서 Sass/SCSS 파일을 설정할 수 있습니다.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// ...
theme: {
customCss: [require.resolve('./src/css/custom.scss')],
},
// ...
},
],
],
};

Sass/SCSS을 모듈로 사용하기

스타일 시트 파일명을 .css 확장자 대신 .module.scss 확장자로 설정(welcome.module.scss)합니다. 웹팩에서 sass-loader를 사용해 여러분이 만든 스타일 시트를 전처리하고 CSS 모듈처럼 파일을 로드합니다.

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>
);
}