Tinyrack Docs · Tinyrack Design System

Tinyrack Docs는 MDX와 TSX 파일을 내비게이션, 검색, 언어 대체 경로, SEO 에셋, Tinyrack UI를 갖춘 정적 React Router 문서 사이트로 만들어요. 이 가이드는 빈 프로젝트에서 시작해 프로덕션 빌드를 만드는 과정까지 다뤄요. Node.js 24 이상이 필요해요.

1. 패키지 설치

React 19, React Router 8과 함께 문서 런타임을 설치하세요. React Router, Tailwind CSS 4, Vite 빌드 도구는 개발 의존성으로 두세요.

pnpm add @tinyrack/docs @tinyrack/ui react react-dom react-router
pnpm add --save-dev @react-router/dev @tailwindcss/vite tailwindcss vite

2. 사이트 설정

프로젝트 루트에 docs.config.ts를 만드세요. contentDir는 문서 라우트를 담은 디렉터리를 가리켜요. 섹션 이름과 사이트 메타데이터는 내비게이션과 생성되는 SEO 에셋에도 사용돼요.

import { defineDocsConfig } from '@tinyrack/docs/config';

export default defineDocsConfig({
  contentDir: 'app/content',
  i18n: {
    defaultLocale: 'en',
    locales: {
      en: { label: 'English', language: 'en', openGraph: 'en_US' },
      ko: { label: '한국어', language: 'ko', openGraph: 'ko_KR' },
    },
  },
  redirects: { '/': '/en/' },
  sections: [
    { id: 'start', label: { en: 'Start', ko: '시작하기' }, order: 0 },
    { id: 'guides', label: { en: 'Guides', ko: '가이드' }, order: 1 },
  ],
  site: {
    basePath: '/',
    description: 'Documentation for this project.',
    favicon: '/favicon.svg',
    locale: { language: 'en', openGraph: 'en_US' },
    logo: { dark: '/logo-inverse.svg', light: '/logo.svg' },
    title: 'Project Docs',
    url: 'https://docs.example.com',
  },
  theme: { default: 'auto' },
});

theme.default에는 auto, light, dark를 지정할 수 있어요. auto는 운영 체제의 색상 모드를 따라요. 방문자가 헤더에서 선택한 값은 설정한 기본값보다 우선하며 다음 방문에도 유지돼요.

로고와 파비콘 파일은 public/에 두세요. 사이트가 도메인 루트가 아니라 /docs 같은 하위 경로에서 제공된다면 site.basePath를 바꾸세요.

3. React Router와 Vite 연결

React Router 라우트 정의와 프레임워크 설정을 만드세요. 두 파일이 같은 Docs 설정을 사용하므로 라우트 탐색과 정적 출력이 일치해요.

// app/routes.ts
import { createDocsRoutes } from '@tinyrack/docs/react-router';
import config from '../docs.config.js';

export default createDocsRoutes(config);

// react-router.config.ts
import { createDocsRouterConfig } from '@tinyrack/docs/react-router';
import config from './docs.config.js';

export default createDocsRouterConfig(config);

Tinyrack Docs 플러그인을 Tailwind CSS 플러그인보다 먼저 등록하세요.

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { tinyrackDocs } from '@tinyrack/docs/vite';
import { defineConfig } from 'vite';
import config from './docs.config.js';

export default defineConfig({
  plugins: [...tinyrackDocs(config), tailwindcss()],
});

생성된 모든 라우트에 문서 셸, 메타데이터, Tinyrack 테마가 적용되도록 패키지에서 제공하는 루트와 스타일시트를 사용하세요.

/* app/styles/tinyrack-docs.css */
@import "@tinyrack/docs/styles.css";

// app/root.tsx
import './styles/tinyrack-docs.css';

export { default, Layout, links, meta } from '@tinyrack/docs/runtime';

4. MDX 페이지 추가

contentDir 아래의 모든 .mdx와 .tsx 파일은 재귀적으로 라우트가 돼요. app/content/en/getting-started.mdx를 만들면 파일 이름이 /en/getting-started/에 대응해요. Tinyrack Docs가 페이지 제목과 설명을 렌더링하므로 직접 작성하는 제목은 2단계부터 시작하세요.

---
title: "Getting started"
description: "Install and configure the project."
section: start
order: 0
---

## Install

Install the package with your package manager.

order는 선택 사항이에요. order를 지정한 페이지가 섹션 안에서 먼저 나오고, 나머지 페이지는 사이드바 라벨의 알파벳순으로 이어져요.

가져오는 컴포넌트, 예제, 헬퍼는 contentDir 밖에 두세요. 이 디렉터리 안에 둔 지원 파일은 별도의 문서 라우트로 처리돼요.

5. TSX 페이지 추가

라우트에 별도의 React 구성이 필요하면 DocsPage를 사용하세요. app/content/en/status.tsx 파일은 /en/status/에 대응해요.

import { DocsPage } from '@tinyrack/docs/runtime';

export default function StatusPage() {
  return (
    <DocsPage
      frontmatter={{
        title: 'Status',
        description: 'Review the current service status.',
        section: 'guides',
        order: 0,
      }}
      headings={[{ depth: 2, id: 'services', label: 'Services' }]}
    >
      <h2 id="services">Services</h2>
      <p>All systems are operational.</p>
    </DocsPage>
  );
}

frontmatter와 선택 항목인 headings는 정적 인라인 객체 리터럴이어야 해요. 라우트 탐색 단계에서는 변수, 스프레드, 계산된 값, 함수 호출, 템플릿 표현식을 읽을 수 없어요. headings에 선언한 모든 id는 실제로 렌더링한 제목과 일치해야 해요.

6. 사이트 실행과 빌드

package.json에 React Router 명령을 추가하세요.

{
  "scripts": {
    "dev": "react-router dev",
    "build": "react-router build",
    "preview": "vite preview"
  }
}

pnpm dev를 실행하고 생성된 MDX와 TSX 라우트를 여세요. 사이드바 링크와 페이지 목차가 콘텐츠와 일치하는지 확인한 다음 pnpm build를 실행하세요. 프로덕션 빌드는 정적 라우트, 리디렉션, Pagefind 검색 인덱스, 사이트맵, robots 파일, 소셜 이미지와 그 밖의 SEO 에셋을 만들어요. pnpm preview로 빌드 결과를 로컬에서 확인할 수 있어요.

7. 내비게이션과 로케일 조정

로케일 디렉터리 아래에서 상대 경로가 같은 파일은 서로 언어 대체 경로가 돼요. 예시 설정에서는 en/getting-started.mdx와 ko/getting-started.mdx가 연결돼요. 영어, 한국어, 일본어 인터페이스 문구가 기본 제공되며, 필요한 경우 로케일별로 일부 문구만 덮어쓸 수 있어요.

기본 사이드바는 섹션으로 구성돼요. 섹션 안에서는 order를 지정한 페이지가 먼저 나오고, 나머지는 사이드바 라벨의 알파벳순으로 정렬돼요. 섹션 설정에 groups를 선언하고 페이지 frontmatter에 group을 지정하면 접을 수 있는 하위 그룹으로 묶을 수 있어요. 명시적인 그룹이나 외부 링크가 필요하면 재귀적인 navigation 설정을 사용하세요. 헤더 경로에는 /{locale}을 넣어 내부 링크가 현재 언어를 유지하도록 할 수 있어요. MDX에서는 추가 설정 없이 CommonMark, GFM, 코드 하이라이트와 :::caution 같은 콜아웃 지시문을 사용할 수 있어요.

Tinyrack Docs에는 프로젝트 생성기, 전용 CLI, 런타임 MDX 컴파일러, 배포 서비스가 포함되지 않아요. 배포 설정은 사용하는 프로젝트에서 관리하고 대상 호스트에서 프로덕션 빌드를 확인하세요.

문서 사이트가 아닌 제품 애플리케이션에 Tinyrack UI를 추가하려면 설치를 따라 하세요. 기존 애플리케이션에서 신뢰할 수 있는 MDX를 렌더링하려면 MDX 컴포넌트 맵을 사용하세요.