Version: 2.0.0-beta.5 🚧

페이지 만들기

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

쇼케이스나 코드 연습 또는 기술 지원 안내 페이지 등 독립적인 페이지를 만들 때 유용한 방법입니다.

페이지에서 사용할 수 있는 기능은 @docusaurus/plugin-content-pages에서 처리합니다.

리액트 컴포넌트나 마크다운을 사용할 수 있습니다.

note

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

info

Check the Pages Plugin API Reference documentation for an exhaustive list of options.

리액트 페이지 추가하기#

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

/src/pages/helloReact.js

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

파일을 저장하면 배포 서버에서 자동으로 변경사항을 반영해 새로고침합니다. http://localhost:3000/helloReact을 열어보면 방금 만든 새로운 페이지를 확인할 수 있습니다.

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

tip

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

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

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

/src/pages/helloMarkdown.md

---title: my hello page titledescription: my hello page descriptionhide_table_of_contents: true---
# Hello
How are you?

리액트 페이지와 마찬가지로 http://localhost:3000/helloMarkdown에서 만들어진 페이지를 확인할 수 있습니다.

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

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

tip

마크다운 페이지 내에서도 리액트의 강력한 기능을 사용할 수 있습니다. 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│       └── support│           ├── index.js│           └── styles.module.css.

caution

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

리액트 사용하기#

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

경로 중복#

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