AGENTS.md

프로젝트 개요

ipari-note는 개인 노트 겸 블로그 애플리케이션입니다.

main.py가 Flask 앱을 만들고 PageWatcher를 별도 데몬 스레드로 실행합니다.
app/__init__.py의 create_app()이 설정 로드, 블루프린트 등록, DB 초기화, 설정/사용자 동기화를 수행합니다.
노트 원본은 기본적으로 data/pages 아래의 .md 파일입니다.
app/note/note.py가 마크다운 렌더링, 메타데이터 파싱, DB 업데이트, 페이지/파일 서빙, 피드 생성을 담당합니다.
app/note/markdown.py에는 Python-Markdown 확장, Obsidian 스타일 위키링크/이미지 임베드, YAML 유사 메타데이터, 한글 slug 처리 등 커스텀 마크다운 동작을 담당합니다.
기본 테마는 themes/yaong이며 템플릿과 정적 파일이 이곳에 있습니다.

ipari-note는 frontmatter의 다음 속성을 사용합니다.

이 프로젝트는 Python Flask 애플리케이션입니다. Linux, MacOS, WSL2 등 여러 환경에서 작동을 보장해야합니다.

의존성은 requirements.txt를 기준으로 설치합니다.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

런타임에는 저장소 루트에 다음 파일이 필요합니다. 실제 파일은 .gitignore 대상이며 샘플은 *.bak로 제공됩니다.

샘플을 복사해 로컬에서 실행할 수 있습니다.

cp config.py.bak config.py
cp config.yml.bak config.yml
cp user.yml.bak user.yml
mkdir -p data/pages
python3 main.py

main.py는 watcher 스레드를 함께 띄웁니다. 단순 라우팅/렌더링 테스트나 모듈 단위 확인에서는 전체 앱 부팅보다 필요한 모듈을 스텁으로 격리하는 편이 안전합니다.

현재 테스트는 unittest 기반이며 pytest로도 실행할 수 있는 형태입니다.

python3 -m unittest discover -s tests

tests/test_markdown.py: app/note/markdown.py를 직접 로드하고 Config를 스텁 처리해 마크다운 확장 동작을 검증합니다.
tests/test_tags.py: app/main/view.py를 직접 로드하고 노트/사용자 의존성을 스텁 처리해 중첩 태그 라우팅을 검증합니다.

마크다운 파서, 라우팅 규칙, 태그/메타데이터 파싱, 권한 처리처럼 사용자 노트 URL이나 렌더링 결과가 바뀌는 작업에는 회귀 테스트를 추가하거나 갱신하세요.