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

스타일과 레이아웃

tip

This section is focused on styling through stylesheets. If you find yourself needing to update the DOM structure, you can refer to swizzling.

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

기본 설정과 만들고자 하는 웹 사이트 유형에 따라 몇 가지 접근 방식과 프레임워크가 있습니다. 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 into the preset.

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 stable class names in your custom CSS.
  • Infima class names. These class names 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 predefined CSS class names for global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS.

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',
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)를 기본 스타일 프레임워크로 사용합니다. Infima provides a flexible layout and common UI components styling suitable for content-centric websites (blogs, documentation, landing pages). 좀 더 자세한 사항은 인피마 웹 사이트를 참고하세요.

When you scaffold your Docusaurus project with create-docusaurus, the website will be generated with basic Infima stylesheets and default styling. You can override Infima CSS variables globally.

/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; and 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.

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

Mobile View

Docusaurus uses 966px as the cutoff between mobile screen width and desktop. If you want your layout to be different in the mobile view, you can use media queries.

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

CSS 모듈

CSS 모듈을 사용해 스타일을 적용하려면 스타일 시트 파일명을 .module.css 확장자로 설정해야 합니다(welcome.module.css). 웹팩에서는 해당 확장자로 설정한 CSS 파일을 로드하고 여러분은 가져온 CSS 모듈에서 클래스 이름(일반 문자열을 사용하지 않고)을 참조해야 합니다. 리액트 앱 만들기 가이드에서 사용하는 방법과 비슷한 명명 규칙입니다.

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

The class names will be processed by webpack into a globally unique class name during build.

자바스크립트로 CSS 작성하기

caution

Lifecycle API는 아직 개발 진행중입니다. 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>
);
}