버전: 2.1.0

페이지 만들기

이번에는 도큐사우루스에서 페이지를 만드는 방법을 살펴보겠습니다.

@docusaurus/plugin-content-pages 플러그인을 사용하면 쇼케이스 페이지, 플레이그라운드 페이지 또는 지원 페이지와 같은 독립적인 별도 페이지를 만들 수 있습니다. 리액트 컴포넌트나 마크다운을 사용할 수 있습니다.

노트

페이지는 사이드바를 가지지 않습니다. 사이드바는 문서만 가질 수 있습니다.

정보

전체 옵션 목록은 페이지 플러그인 API 레퍼런스 문서를 참고하세요.

리액트 페이지 추가하기

리액트는 페이지를 만들기 위한 UI 라이브러리처럼 사용됩니다. 모든 페이지 컴포넌트는 리액트 컴포넌트로 내보내야 합니다. 이를 통해 다채롭고 상호작용할 수 있는 콘텐츠를 만드는 데 리액트의 다양한 기능을 활용할 수 있습니다.

아래와 같은 내용으로 /src/pages/helloReact.js 파일을 만듭니다.

/src/pages/helloReact.js
import React from 'react';
import Layout from '@theme/Layout';

export default function Hello() {
  return (
    <Layout title="Hello" description="Hello React Page">
      <div
        style={{
          display: 'flex',
          justifyContent: 'center',
          alignItems: 'center',
          height: '50vh',
          fontSize: '20px',
        }}>
        <p>
          Edit <code>pages/helloReact.js</code> and save to reload.
        </p>
      </div>
    </Layout>
  );
}

파일을 저장하면 배포 서버에서 자동으로 변경사항을 반영해 새로고침합니다. Now open http://localhost:3000/helloReact and you will see the new page you just created.

개별 페이지는 별도의 스타일 설정을 가지고 있지 않습니다. 그래서 @theme/Layout에서 Layout 컴포넌트를 가져와줘야 합니다. 이렇게 하면 콘텐츠를 컴포넌트가 감싸는 형태가 되어 메뉴바나 푸터가 화면에 표시됩니다.

팁

.tsx 확장자를 가지는 타입스크립트 페이지를 생성할 수도 있습니다(helloReact.tsx).

마크다운 페이지 추가하기

아래와 같은 내용으로 /src/pages/helloMarkdown.md 파일을 만듭니다.

/src/pages/helloMarkdown.md
---
title: my hello page title
description: my hello page description
hide_table_of_contents: true
---

# Hello

How are you?

In the same way, a page will be created at http://localhost:3000/helloMarkdown.

마크다운 페이지는 테마 레이아웃만을 사용하기 때문에 리액트 페이지에 비해 다양한 형식을 취할 수는 없습니다.

마크다운 페이지 예제에서 다른 예제를 확인할 수 있습니다.

팁

마크다운 페이지 내에서도 리액트의 강력한 기능을 사용할 수 있습니다. MDX 문서를 참고하세요.

라우팅

지킬(Jekyll)이나 넥스트(Next) 같은 정적 사이트 생성 도구에 익숙하다면 라우팅을 사용해봤을 겁니다. /src/pages/ 디렉터리 내에 만든 자바스크립트 파일은 /src/pages/ 디렉터리 계층 구조에 따라 자동으로 웹사이트 페이지로 변환됩니다. 예를 들면 아래와 같은 형식입니다.

/src/pages/index.js → [baseUrl]
/src/pages/foo.js → [baseUrl]/foo
/src/pages/foo/test.js → [baseUrl]/foo/test
/src/pages/foo/index.js → [baseUrl]/foo/

컴포넌트 기반 개발 시에는 스타일, 마크업, 동작 관련 파일을 컴포넌트와 같은 위치에서 관리하는 것이 좋습니다. 각각의 페이지는 컴포넌트입니다. 페이지 디자인을 다른 스타일로 적용하고자 한다면 페이지 컴포넌트와 같은 디렉터리에 스타일 파일을 위치시키는 것을 권장합니다. 예를 들어 "Support" 페이지를 만들고자 한다면 아래 방법 중에서 선택할 수 있습니다.

/src/pages/support.js 파일을 추가합니다.
/src/pages/support/ 디렉터리를 만들고 /src/pages/support/index.js 파일을 추가합니다.

두 번째 방법은 디렉터리 안에 페이지와 관련된 파일을 관리할 수 있는 장점이 있기 때문에 권장하는 방법입니다. 예를 들어 "Support" 페이지 스타일만을 위해 사용하는 CSS 모듈 파일(styles.module.css)이 있다고 합시다.

노트

컴포넌트 모듈 내에서 CSS 모듈 파일을 직접 가져오는 경우에 사용하는 디렉터리 구조입니다(support/index.js).

기본적으로 파일명이 _로 시작하는 마크다운이나 자바스크립트 파일은 무시합니다. 해당 파일은 라우팅 대상에서 제외됩니다(exclude 옵션을 확인하세요).

my-website
├── src
│   └── pages
│       ├── styles.module.css
│       ├── index.js
│       ├── _ignored.js
│       ├── _ignored-folder
│       │   ├── Component1.js
│       │   └── Component2.js
│       └── support
│           ├── index.js
│           └── styles.module.css
.

warning

src/pages/ 디렉터리 안에 있는 모든 자바스크립트, 타입스크립트 파일은 각 파일에 대응하는 웹사이트 경로가 생성됩니다. 해당 디렉터리에 재사용할 수 있는 컴포넌트를 만들고자 한다면 exclude 옵션을 사용합니다(기본적으로 파일 이름이 _으로 시작하거나 테스트 파일(.test.js), __tests__ 디렉터리 안에 있는 파일은 페이지로 변환되지 않습니다).

경로 중복

실수로 같은 경로를 가리키는 페이지를 여러 개 만들 수 있습니다. 이런 일이 생기면 도큐사우루스에서는 yarn start 또는 yarn build 명령을 실행할 때 경고 메시지를 표시합니다. 하지만 사이트는 정상적으로 생성됩니다. 마지막에 만든 페이지가 충돌이 발생한 페이지를 덮어쓰게 됩니다. 이런 문제를 해결하기 위해서는 경로 중복이 발생한 페이지를 수정하거나 삭제해야 합니다.

페이지 만들기

리액트 페이지 추가하기​

마크다운 페이지 추가하기​

라우팅​

경로 중복​

리액트 페이지 추가하기

마크다운 페이지 추가하기

라우팅

경로 중복