Starlight로 매뉴얼 만들기 #1 설치부터 첫 문서까지

프레임워크 Starlight Documentation Static Site
3 분 소요

문서를 처음 체계적으로 만들다 보면 거의 예외 없이 같은 문제를 만납니다. README 한 장으로는 감당이 안 되는 문서를 어디에 쌓을 것인가 하는 문제입니다. 노션은 외부 공개와 버전 관리가 번거롭고, 블로그 도구로 만들면 글이 시간순으로 나열될 뿐 레퍼런스로 쓰기 불편합니다. 그래서 많은 팀이 문서를 코드처럼 다루는 방식, 곧 Docs as Code로 옮겨 갑니다. 마크다운으로 쓰고, Git으로 관리하고, 정적 사이트로 배포하는 방식입니다.

이 시리즈는 그 첫 단추인 정적 사이트 생성기로 문서 사이트를 짓는 법을 다룹니다. 도구는 Starlight입니다. 모던 웹 프레임워크 Astro 위에 올라간 문서 테마로, 기본적으로 JS를 거의 보내지 않아 가볍고 빠른 것이 강점입니다. 검색과 다국어도 기본으로 갖췄습니다.

이번 시리즈는 Starlight로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지 ← 이번 글
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, asides
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색, 접근성, 문서 문화

이번 글은 Starlight가 무엇을 준비물로 요구하는지, 그리고 새 사이트를 만들어 개발 서버로 첫 문서를 띄우는 데까지를 직접 실행해 보며 마무리하겠습니다.

준비물 — Node.js #

Starlight는 Astro 위에서 도는 도구라, 준비물은 Node.js 18 버전 이상입니다. 설치 후 버전을 확인합니다.

버전 확인 
node --version

Docusaurus와 마찬가지로 자바스크립트 생태계 위에서 움직이지만, Astro는 필요한 곳에만 JS를 입히는 구조라 결과물이 더 가볍습니다.

새 사이트 만들기 #

Astro의 생성기에 Starlight 템플릿을 지정하면, 문서 사이트의 뼈대가 한 번에 만들어집니다.

새 사이트 생성 
npm create astro@latest -- --template starlight

대화형으로 폴더 이름과 의존성 설치 여부를 물어보며, 끝나면 바로 시작할 수 있는 형태가 됩니다.

첫 문서 띄우기 #

만들어진 폴더로 들어가 개발 서버를 띄웁니다.

개발 서버 실행 
cd my-docs
npm run dev

브라우저에서 http://localhost:4321을 열면 Starlight 레이아웃에 기본 문서가 나타납니다. 파일을 고치면 화면이 즉시 갱신됩니다.

사이트 제목 같은 설정은 astro.config.mjs의 Starlight 통합에서 정합니다.

astro.config.mjs 
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({ title: '제품 매뉴얼' }),
  ],
});

폴더 구조 이해하기 #

생성된 구조에서 당장 알아야 할 곳은 문서가 들어가는 폴더와 설정 파일입니다.

폴더 구조 
my-docs/
├─ astro.config.mjs       # Astro + Starlight 설정
├─ src/
│  └─ content/
│     └─ docs/            # 문서 본문 (여기를 채웁니다)
│        ├─ index.mdx     # 첫 화면
│        └─ guides/example.md
├─ public/                # 이미지 등 정적 파일
└─ dist/                  # npm run build 산출물 (배포용)

문서를 늘리는 일은 결국 src/content/docs 아래에 마크다운 파일을 더하는 일입니다. Starlight는 이 폴더 구조를 바탕으로 사이드바를 자동으로 만들고, 필요하면 직접 정의할 수도 있습니다. 그 방법은 다음 편에서 다룹니다.

마무리 #

이번 글에서는 Node.js를 준비하고, create astro로 Starlight 사이트를 생성해 개발 서버로 첫 문서를 띄우는 데까지 마쳤습니다. Starlight는 Node 기반이면서도 결과물이 가볍고, 검색까지 기본으로 딸려 온다는 점이 강점입니다.

다음 편에서는 사이드바와 검색을 다룹니다. 문서가 수십 편으로 늘어도 독자가 길을 잃지 않도록 정보 구조를 설계하는 방법을 살펴보겠습니다.

X