콘텐츠로 이동

블로그 메뉴와 글 관리

이 블로그는 폴더와 .pages 파일을 이용해 메뉴를 만든다. 글을 시리즈 순서로 읽는 왼쪽 메뉴와, 현재 글의 내용을 찾는 오른쪽 목차를 구분한다.

메뉴와 URL의 역할

MkDocs는 nav를 생략하면 기본적으로 파일을 탐색해 메뉴를 구성한다. awesome-pages는 여기에 .pages를 이용한 이름·순서 제어를 추가한다. 플러그인이 HTTP 동적 라우터를 만드는 것은 아니다. 빌드 시 문서 경로에 대응하는 정적 페이지가 만들어진다.

현재는 mkdocs.yml에 nav를 따로 선언하지 않고 다음 플러그인을 사용한다.

plugins:
  - search
  - awesome-pages

기존 블로그 관리 글은 docs/blog/에 그대로 두어 주소를 유지한다.

왼쪽 사이드바

홈
전체 글
Local LLM Study
  ├── 시리즈 소개
  └── 1주차 — Homebrew & Ollama
블로그 관리
  ├── 초기 환경 세팅
  ├── 메뉴와 글 관리
  └── Copyright 수정

navigation.tabs를 사용하지 않으므로 최상위 항목이 상단 탭으로 빠지지 않는다. navigation.sections도 사용하지 않아 주제를 접고 펼칠 수 있다. navigation.indexes로 시리즈 제목을 소개 페이지와 연결한다. 작은 화면에서는 메뉴 버튼으로 탐색 메뉴를 연다.

홈에서는 오른쪽 목차만 숨긴다. navigation을 hide에 추가하면 그 페이지에서 왼쪽 메뉴도 사라진다.

---
hide:
  - toc
---

폴더 구성과 순서

docs/
├── .pages
├── index.md
├── articles/index.md
├── local-llm/
│   ├── .pages
│   ├── index.md
│   └── 01-week-01.md
└── blog/
    ├── .pages
    └── 01-blog-installation.md

최상위 docs/.pages는 메뉴 순서를 지정한다.

arrange:
  - index.md
  - articles
  - local-llm
  - blog

docs/local-llm/.pages는 시리즈 이름과 주차 순서를 지정한다.

title: Local LLM Study
arrange:
  - index.md
  - 01-week-01.md

arrange에 없는 문서도 기본적으로 자동 탐색 대상이다. 발행하지 않을 템플릿과 메모는 docs/ 밖에 둔다. 테마 템플릿도 루트의 overrides/에 보관한다.

글 추가 절차

  1. templates/post.md를 참고해 주제 폴더에 글을 작성한다.
  2. 제목, 설명, 실제 작성일과 태그를 기록한다. 날짜·태그는 메타데이터이며 현재 자동 아카이브나 태그 페이지를 만들지는 않는다.
  3. 시리즈의 index.md에 글 링크를 넣고 .pages로 순서를 지정한다.
  4. 전체 글과 홈의 최근 글 목록에 링크를 추가한다. 두 목록은 현재 수동으로 관리한다.
  5. uv run --locked mkdocs build --strict로 빌드한 뒤 로컬 미리보기에서 확인한다.

실험 글은 각 단계 안에 목적·조건 → 실제 명령어 → 결과 원문 → 해석·한계를 함께 배치한다. 긴 로그는 아래처럼 접어 두고, 코드 블록 안의 원문은 축약하지 않는다.

<details markdown="1">
<summary>요청별 서버 로그 원문 펼치기</summary>

```text
실제로 확보한 로그를 이 위치에 넣습니다.
```

</details>

참고