빠른 시작

이 문서는 처음 참여하는 작성자나 운영자가 로컬 실행부터 첫 문서 생성까지 한 번에 따라올 수 있도록 구성한 시작 가이드입니다. 실행 명령, 핵심 설정 파일, 문서 생성 규칙을 순서대로 설명해 초기 세팅에서 생기는 혼선을 줄이는 데 목적이 있습니다. 아래 순서를 그대로 따라 하면 로컬 미리보기와 사이드바 반영까지 바로 확인할 수 있습니다.

실행

실행은 저장소 루트에서 시작하며, 의존성 설치 후 개발 서버를 올리는 순서로 진행합니다. 처음 실행 시에는 패키지 설치 시간이 걸릴 수 있으므로 설치 완료 후 로그를 확인한 뒤 다음 단계로 이동하는 것이 좋습니다.

명령어 1: 의존성 설치

pnpm install

이 명령어는 문서 사이트 실행에 필요한 패키지를 로컬에 설치합니다. 설치가 완료되면 오류 없이 종료되는지 먼저 확인한 뒤 다음 명령으로 넘어가야 이후 단계에서 원인 추적이 쉬워집니다.

명령어 2: 개발 서버 실행

pnpm run dev

이 명령어는 로컬 미리보기 서버를 실행하며 일반적으로 http://localhost:4321에서 문서를 확인할 수 있습니다. 문서를 수정했을 때 화면이 즉시 갱신되는지 확인하면 작성 환경이 정상 동작하는지 빠르게 점검할 수 있습니다.

명령어 3: 정적 빌드 검증

pnpm run build

이 명령어는 배포용 정적 산출물을 생성하며, 문서 링크나 플러그인 처리 오류를 사전에 점검하는 단계입니다. 로컬 미리보기는 정상이어도 빌드에서 실패할 수 있으므로 배포 전에는 반드시 단독 실행해 결과를 확인해야 합니다.

명령어 4: 빌드 결과 프리뷰

pnpm run preview

이 명령어는 pnpm run build 결과를 실제 배포와 유사한 형태로 확인하는 단계입니다. 개발 서버 화면과 프리뷰 화면이 동일하게 보이는지 비교하면 배포 직전 품질 검증을 더 안정적으로 수행할 수 있습니다.

핵심 설정 파일

설정 파일은 역할별로 나누어 관리됩니다. 아래 구조를 먼저 익혀 두면 기능 수정 시 어느 파일을 열어야 하는지 빠르게 판단할 수 있습니다.

docs/
- astro.config.mjs
- public/
  - directives.js
- src/
  - plugins/
    - remarkDirectiveComponents.js
    - remarkObsidianEmbed.js
    - rehypeImage.js
    - rehypeVideo.js
    - contentMediaIntegration.js

파일 역할

docs/astro.config.mjs: 사이트 메타, 사이드바 자동 생성, 플러그인 연결, head 스크립트 설정
docs/src/plugins/*: 마크다운/디렉티브/미디어 처리 로직
docs/public/directives.js: 탭/아코디언/복사 등 클라이언트 런타임 동작

첫 문서 추가

첫 문서는 section/slug/index.md 구조로 생성합니다. 미디어 파일을 같은 폴더에 함께 두면 경로 관리가 단순해지고, 문서 이동 시에도 링크 수정 범위가 줄어듭니다.

docs/
- src/
  - content/
    - docs/
      - markdown-guide/
        
        my-first-doc/
        
        index.md
        
        image.png
        
        demo.mp4

작성 절차

docs/src/content/docs/<section>/<slug>/index.md 생성
frontmatter에 title, description 작성
이미지/비디오가 있으면 같은 폴더에 저장
pnpm run dev에서 문서 렌더링 확인
사이드바에 문서 제목이 자동 노출되는지 확인

첫 문서 템플릿

아래 템플릿으로 시작하면 기본 메타 정보 누락을 방지할 수 있습니다. 제목과 설명은 검색/공유 품질에 직접 영향을 주므로 문서 목적이 드러나게 작성하는 것이 좋습니다.

---
title: 내 첫 문서
description: 문서 목적을 한두 문장으로 설명합니다.
---

문서 본문을 여기에 작성합니다.

초기 점검 체크리스트

초기 작성에서는 구조보다 실행 확인이 우선입니다. 아래 항목을 체크하면 첫 문서 등록 과정에서 발생하는 대부분의 문제를 사전에 제거할 수 있습니다.

개발 서버 접속 확인 (http://localhost:4321)
문서 제목/설명 정상 표시 확인
이미지/비디오 경로 정상 렌더링 확인
사이드바 자동 반영 확인
빌드(pnpm run build) 성공 확인