Sites & Docs

Hextra Roadmap KB

hextra-roadmap-kb

Scaffold a topic learning-roadmap site on Hugo + Hextra — hero home, numbered roadmap docs by category, Labs, Tools, a Blog with RSS and a termbase-backed glossary.

hugohextraroadmapglossary
Install
mkdir -p ~/.claude/skills && curl -fsSL https://skill.metacog.co.kr/dist/hextra-roadmap-kb.zip \
  -o /tmp/hextra-roadmap-kb.zip && unzip -oq /tmp/hextra-roadmap-kb.zip -d ~/.claude/skills
Files19
Size31.3 KB
Bundled foldersassets/
LicenseMIT

This skill produces Korean-language output by default.

Authored by jeonck (MIT) · Browse files on GitHub · Download zip

When Claude uses it

Scaffolds a Korean-language Hugo + Hextra "topic learning roadmap" knowledge-base site — the same structure as the ai-security project (hero home with feature grid, numbered docs roadmap split into categories, Labs, Tools/References, Blog with RSS, and a Glossary backed by data/ko/termbase.yaml), plus a GitHub Pages Actions deploy workflow. Use when the user asks to build a new topic-based Korean learning/knowledge-base site, or to replicate the ai-security project's structure for a different subject (e.g. "이 프로젝트 형태로 OO 주제 사이트 만들어줘").

SKILL.md

Hextra Roadmap KB Builder

새로운 주제(topic)에 대해, ai-security 프로젝트와 동일한 형태의 "학습 로드맵형" 지식베이스를 빠르게 만듭니다.

사이트 구조 개요

content/
  _index.md            # 홈 (layout: hextra-home, 히어로 + feature-grid)
  docs/
    _index.md           # 로드맵 개요 (추천 순서, 배경별 진입점, N주 플랜, 전체 섹션 카드)
    <category-1>/
      _index.md         # "① 카테고리명" weight=1, 토픽 카드 목록
      <topic-a>.md
      <topic-b>.md
    <category-2>/
      _index.md         # "② 카테고리명" weight=2
      ...
  labs/
    _index.md           # 실습 목록 + 환경설정 안내 + 안전 경고
    lab1-*.md
    lab2-*.md
  tools/
    _index.md           # 도구/표준 참고자료 개요
    *.md                 # 도구셋별 페이지
  blog/
    _index.md           # RSS 배지 + 소개
    *.md                 # 포스트
  glossary/
    _index.md           # layout: glossary
data/
  ko/
    termbase.yaml        # {{< term "용어" >}} 숏코드가 참조하는 용어집 데이터
assets/
  css/
    custom.css           # 좌측 사이드바 접기/펼치기 토글 스타일
  js/
    core/
      sidebar-toggle.js  # 좌측 사이드바 접기/펼치기 토글 스크립트
.github/workflows/
  deploy.yml             # Hugo build + GitHub Pages 배포
hugo.toml
.gitmodules
.gitignore

핵심 아이디어:

시작 전에 — 필요한 입력값

작업을 시작하기 전에 사용자에게서 다음 정보를 확보하거나, 합리적으로 추정해 확인받습니다:

  1. 주제(topic): 예) "AI Security" → "클라우드 보안", "재무제표 분석" 등
  2. 사이트 제목 / GitHub repo 이름 / GitHub 사용자명 → baseURL, GITHUB_URL 결정
  3. docs 카테고리 N개 (보통 5~6개): 각 카테고리의 한글명, 1줄 설명, 아이콘 후보
  1. 추천 학습 순서와 그 이유 (callout에 들어갈 한 단락)
  2. 배경별 진입점 (예: GRC / AppSec / ML Engineer 같은 독자 유형 2~3개)
  3. 각 카테고리별 토픽 페이지 목록 (카테고리당 보통 3~4개)
  4. Labs 2개 이상: 실습 제목/목표, 필요 패키지
  5. Tools 섹션 카테고리 (보통 2~3개 도구 묶음 + "표준 및 참고 문서")
  6. 용어집 용어 10~20개

위 정보가 부족하면, ai-security 프로젝트(content/, hugo.toml, data/ko/termbase.yaml)를 참고용 실례로 보여주고 동일한 패턴으로 새 주제에 맞게 제안한 뒤 사용자 확인을 받습니다.

워크플로우

1. Hugo 프로젝트 초기화

hugo new site . --force --format toml
git init
mkdir -p themes
git submodule add https://github.com/imfing/hextra.git themes/hextra

2. hugo.toml 작성

assets/hugo.toml.template을 복사해 hugo.toml로 저장하고 다음 플레이스홀더를 채웁니다:

메뉴 구조(실습/도구/블로그/용어집/GitHub/검색)는 그대로 유지합니다.

3. 홈페이지 (content/_index.md)

assets/home.md.template을 기반으로:

4. docs 로드맵 개요 (content/docs/_index.md)

assets/docs-index.md.template 기반으로 작성. 포함 요소:

5. 카테고리별 섹션 (content/docs/<category>/_index.md)

각 카테고리마다 assets/category-index.md.template 기반으로:

각 토픽 페이지는 assets/topic-page.md.template 기반 (title, weight + 자유 서술 + 다른 섹션으로의 교차 링크 callout).

6. Labs 섹션 (content/labs/)

7. Tools 섹션 (content/tools/)

8. Blog 섹션 (content/blog/)

9. Glossary + termbase (content/glossary/, data/ko/)

10. GitHub Pages 배포

11. 좌측 사이드바 접기/펼치기 토글

주의 사항

알려진 함정 (ai-security 프로젝트에서 실제로 발생한 문제)

1. 내부 링크 404 — pretty URL의 상대 경로 깊이

Hugo는 content/docs/<category>/<page>.md를 leaf bundle pretty URL /docs/<category>/<page>/로 렌더링합니다. 즉 렌더링된 페이지 경로는 소스 파일 경로보다 한 단계 더 깊습니다. 본문에서 상대 링크를 쓸 때 다음 규칙을 지켜야 합니다.

콘텐츠 작성이 끝나면 hugo server --disableFastRender로 띄운 뒤, sitemap을 크롤링해 모든 <a href>를 실제로 요청해보는 스크립트로 깨진 링크가 0개인지 확인합니다.

2. LaTeX/KaTeX 수식이 렌더링되지 않음

assets/hugo.toml.template에는 이미 다음 설정이 포함되어 있으므로 그대로 사용하면 문제없지만, 이 설정 없이는 $x$, $$...$$ 같은 수식이 원본 텍스트로 그대로 노출됩니다 (goldmark의 passthrough 확장이 없으면 Hextra의 render-passthrough.html 훅이 호출되지 않아 hasMath가 세팅되지 않고 KaTeX 스크립트가 로드되지 않음):

[markup.goldmark.extensions.passthrough]
  enable = true
  [markup.goldmark.extensions.passthrough.delimiters]
    block = [['\[', '\]'], ['$$', '$$']]
    inline = [['\(', '\)'], ['$', '$']]

수식이 포함된 페이지가 있다면, 로컬 빌드 후 렌더링 결과에 katex/katex-display 클래스가 생성되는지 확인합니다.

3. 한글 조사가 붙는 볼드가 렌더링되지 않음

CommonMark의 "right-flanking delimiter" 규칙 때문에, 닫는 바로 앞이 구두점(), ", ' 등)이고 바로 뒤에 공백 없이 한글 조사(는/은/이/가/을/를/와/과/의/에/로 등)나 영문/숫자가 붙으면 가 강조를 닫지 못하고 그대로 텍스트로 노출됩니다.

예: NIST AI RMF(AI RMF)는 → **가 글자 그대로 출력됨.

수정 방법은 닫는 ** 바로 앞을 영문/한글 글자로 만들어주는 것 — 구두점을 강조 밖으로 빼냅니다:

콘텐츠 작성 후 다음 스크립트로 모든 페이지를 스캔해 0건인지 확인합니다:

python3 - <<'EOF'
import re, glob
pattern = re.compile(r'<div class="content">(.*?)</main>', re.S)
for f in glob.glob("public/**/index.html", recursive=True):
    html = open(f, encoding="utf-8").read()
    m = pattern.search(html)
    body = m.group(1) if m else ""
    if "**" in body:
        print(f, body.count("**"))
EOF

More in Sites & Docs

Algolia for DocusaurusWire Algolia DocSearch into a Docusaurus v3 site on GitHub Pages — automates every config …Docusaurus Site ScaffoldStand up a Docusaurus documentation site with GitHub Pages deployment, grouped navigation,…GitHub Sponsors ButtonAdd a GitHub Sponsors funding button to any static site — Hugo, Jekyll, Docusaurus or plai…Hextra KB BuilderInitialize a technical knowledge base on Hugo's Hextra theme with Mermaid, LaTeX and searc…