AGENT.MD: nyang-police.github.io 블로그 작성/구조 가이드

🧭 목적

이 파일은 nyang-police.github.io Jekyll 블로그의 구조와 글 작성 방법을 정리한 문서입니다.

• 개발자/콘텐츠 작성자를 위한 참조 매뉴얼
• 새 게시글 작성 시 체크리스트
• 기능별 사용 방법 요약

---

📁 프로젝트 주요 구조

• _config.yml: 사이트 정보 및 Jekyll 설정
• Gemfile: Ruby 젬 의존성 관리
• scripts/setup-jekyll.sh: 로컬환경, Jekyll 빌드 도구 설치
• _layouts/: 레이아웃 템플릿 (default.html, post.html)
• _includes/: 재사용 HTML 조각 (pyodide_setup.html, python_editor.html, toc.html, …)
• _posts/: 게시글 저장소
  • docker/
  • python/
  • tools/
  • stargazing/ (신규 카테고리)
  • fun/ (신규 카테고리)
• 최상위 카테고리 페이지: python.md, docker.md, tools.md, programs.md, stargazing.md, fun.md
• assets/, DevLog/, tools.md 등 기타 정적 자원

---

⚙️ _config.yml 핵심 설정

• title: NyangPolice’s homepage
• url: https://blog.cat-police.com (production)
• baseurl: ""
• permalink: pretty
• remote_theme: pages-themes/hacker@v0.2.0
• plugins: jekyll-remote-theme, jekyll-sitemap
• Markdown: kramdown, syntax highlighter rouge
• defaults: assets/**, DevLog/**는 sitemap 제외

---

✍️ 글 작성 규칙

1) 파일 경로

_posts/<category>/<YYYY-MM-DD>-<slug>.md

• category: docker, python, tools 등
• 파일명: 날짜-슬러그 형태

2) frontmatter 필수 예시

---
layout: post
title: "예시 제목"
date: 2026-03-20
author: NyangPolice
category: python
tags: [python, 예제, 입문]
---

3) 필드 설명

• layout: 항상 post 사용
• title: 페이지 상단 큰 제목
• date: 글 발행일
• author: NyangPolice (기본)
• category: python, docker, tools.
• tags: 검색, 분류, 네비게이션
• pyodide: true (Pyodide 인터랙티브 코드 사용 시 추가)

4) 콘텐츠 구조 통계

• 본문 최상단에 제목은 #, 섹션별로 ##, ### 사용
• 코드 블록 사용:
  • 일반 코드: python,bash, ```java 등
  • 주석 명시: 한국어->생략 가능

---

🔧 Pyodide 인터랙티브 코드 삽입

1. frontmatter

pyodide: true

2. 에디터 컴포넌트 포함

<div class="pyodide-block">
    <div class="pyodide-header">
        <span class="pyodide-lang" id="title-1" data-original-title="필요 시 제목">필요 시 제목</span>
        <span class="pyodide-status" id="status-1"></span>
    </div>
    <textarea class="pyodide-code" id="code-1"></textarea>
    <div class="pyodide-controls">
        <button class="pyodide-run-btn"
            onclick="runCode('code-1', 'output-1', 'status-1')">
            ▶ Run
        </button>
        <button class="pyodide-reset-btn" onclick="resetCode('code-1', 'pycode-1')">
            ↺ Reset
        </button>
    </div>
    <textarea class="pyodide-output" id="output-1" readonly>아직 실행되지 않았습니다. ▶ Run을 눌러보세요.</textarea>
    <div class="pyodide-plot" id="plot-1"></div>
</div>

<script>
    document.addEventListener('DOMContentLoaded', function () {
        var src = document.getElementById('pycode-1');
        var ta = document.getElementById('code-1');
        if (src && ta) {
            ta.value = src.textContent.replace(/^\n/, '');
        }
    });
</script>

3. 초기 코드 삽입

<script type="text/plain" id="pycode-1">
print("Hello, World!")
</script>

• id: 포스트 내 고유값
• pycode-<id>: include id와 동일한 숫자
• 여러 에디터가 있는 경우 동일 런타임 공유

---

🧩 레이아웃/포스트 페이지 동작 요약

• _layouts/post.html에서:
  • 기본 TOC 포함 (toc.html)
  • page.pyodide true 시 pyodide_setup.html include
  • page.tags가 있으면 태그 하단 표시
  • 같은 카테고리 글 목록 자동 렌더링

---

▶ 로컬 개발 서버

1. chmod +x scripts/setup-jekyll.sh
2. ./scripts/setup-jekyll.sh
3. source ~/.bashrc
4. bundle exec jekyll serve
5. 브라우저에서 http://localhost:4000

포트 충돌 시: bundle exec jekyll serve --port 4001

---

📦 배포 확인

• GitHub Pages나 커스텀 도메인(blog.cat-police.com)으로 운영
• jekyll-sitemap 플러그인으로 자동 sitemap 생성
• 수동: _site/ 출력 확인

---

💡 추가 팁

• README.md에 작성 모범 사례(토글, 코드 상세 예시, Pyodide 설명)가 있다.
• 새 카테고리 추가 시 _posts/<new-category> 생성 및 frontmatter category: <new-category> 설정.
• permalink: pretty 설정 덕분에 URL은 날짜 없이 깔끔 (e.g. /python/0-python-intro/)
• CNAME 파일에 커스텀 도메인 관리 필요

---

📌 요약

• 블로그는 Jekyll + remote_theme 기반 정적 사이트
• _posts 폴더에 카테고리별 Markdown 파일로 콘텐츠 추가
• post layout에서 pyodide 옵션, 카테고리 링크, 태그 표시 등 자동 처리
• README.md를 따라 세팅 후 bundle exec jekyll serve로 확인