블로그 동적 라우팅 및 메뉴 관리

일반적인 MkDocs의 동작 방식은 새로운 마크다운 글을 작성할 때마다 전역 설정 파일인 mkdocs.yml의 nav: 속성에 파일 경로를 일일이 하드코딩해야 합니다.

본 프로젝트는 이러한 비효율을 제거하기 위해 mkdocs-awesome-pages-plugin을 도입하였으며, 파일 시스템(디렉터리 구조)이 곧 웹사이트의 라우팅 맵이 되도록 자동화했습니다.

1. 동작 원리 및 필수 설정

1) 플러그인 활성화 (mkdocs.yml)

자동 라우팅이 동작하려면 mkdocs.yml 파일에서 nav: 블록을 완전히 삭제해야 합니다.

대신 파일 최하단에 아래와 같이 플러그인을 명시하여 활성화합니다.

plugins:
  - search        # Material 테마의 기본 검색 기능 유지를 위해 필수
  - awesome-pages # 파일 시스템 기반 동적 라우팅 플러그인 활성화

위 설정이 적용되면 docs/ 디렉터리 하위의 모든 폴더와 .md 파일이 스캔되어 좌측 사이드바와 상단 탭(GNB) 메뉴로 자동 변환됩니다.

2. 디렉터리 구조와 네비게이션 매핑 구조

단순히 폴더를 만들면 '알파벳 순서'로 정렬되며 폴더의 영문 이름이 그대로 메뉴에 노출됩니다.

이를 제어하기 위해 각 폴더의 루트에 .pages 라는 메타데이터 파일을 두어 세부 설정을 덮어씁니다(Override).

1) 로컬 디렉터리 구조 예시

docs/
├── .pages               # 1️⃣ 최상위(GNB) 탭 메뉴의 순서를 결정
├── index.md             # '🏠 홈' 화면
├── blog/
│   ├── .pages           # 2️⃣ 'blog' 폴더를 메뉴에서 어떻게 보여줄지 결정
│   ├── 01-installation.md
│   └── 02-dynamic-management.md
└── devops/
    └── .pages           # 3️⃣ 'devops' 폴더를 메뉴에서 어떻게 보여줄지 결정

3. .pages 파일 세부 설정 가이드

해당 디렉터리가 사이트 메뉴에 어떻게 노출될지 결정하는 핵심 파일입니다. YAML 포맷으로 작성됩니다.

1) 메뉴 이름 커스텀 (title)

디렉터리 이름을 그대로 노출하지 않고, 이모지나 한글을 포함한 직관적인 텍스트로 변경합니다.

# 예: docs/blog/.pages
title: 🛠️ 블로그 관리

이 설정을 통해 blog/ 라는 폴더명 대신 화면에는 [🛠️ 블로그 관리] 라는 예쁜 메뉴명으로 출력됩니다.

2) 문서 노출 순서 강제 지정 (arrange)

메뉴의 정렬 순서를 지정합니다. 파일명 또는 하위 폴더명을 리스트 형태로 명시합니다.

여기에 명시되지 않은 파일들은 지정된 파일들 아래에 자동으로 나열됩니다.

# 예: docs/.pages (최상단 메뉴 탭 순서 제어)
arrange:
  - index.md      # 홈을 가장 좌측 탭으로 배치
  - blog          # 블로그 관리 탭을 두 번째로 배치
  - devops        # DevOps 탭을 세 번째로 배치

4. 신규 포스팅 발행 워크플로우

위와 같은 구조가 세팅되어 있으므로, 앞으로 새로운 기술 문서를 작성하는 과정은 매우 단순합니다.

1) 위치 선정 및 글 작성

• 디렉터리 이동: docs/ 내의 적절한 주제 폴더로 이동합니다. (새로운 주제라면 폴더를 생성하고 .pages 파일에 title:을 정의합니다.)
• 문서 작성: 해당 위치에 .md 파일을 생성하고 내용을 작성합니다. 파일의 첫 번째 H1 (# 제목) 태그가 해당 글의 메뉴 이름이 됩니다.

2) 순서 정렬 및 배포

• 순서 정렬 (Optional): 특정 글을 최상단에 고정하고 싶다면 해당 폴더의 .pages 파일 속 arrange: 리스트에 파일명을 추가합니다.
• 배포 (Push): 수동 설정 파일 변경 없이, 작성한 파일만 git commit 및 git push origin main을 수행하면 Cloudflare에 의해 즉각 발행됩니다.