Pandoc과 쉘 스크립트를 활용하는 정적 웹사이트 생성 프롬프트

아래 프롬프트를 Claude Code에서 사용하면 원하는 스타일의 정적 사이트를 만들 수 있습니다. 이 접근법의 장점은 다음과 같습니다.

항목	설명
의존성 최소	Pandoc + bash만 있으면 빌드 가능. 프레임워크 학습 불필요
구조 단순	템플릿 1개, 빌드 스크립트 1개로 전체 파이프라인 파악 가능
콘텐츠 분리	Markdown만 편집하면 되므로 비개발자도 기여 가능
배포 간편	Surge 명령 한 줄로 무료 호스팅 서비스 배포. 별도 서버 설정 불필요
AI 유지보수	CLAUDE.md가 있어서 이후에도 Claude Code가 맥락을 바로 파악

사전 준비

pandoc 설치

OS별 설치 방법은 https://pandoc.org/installing.html 을 참조합니다.

Ubuntu에서는 아래과 같이 설치하실 수 있습니다.

sudo apt-get install -y pandoc

Surge CLI 설치

npm install -g surge로 설치할 수 있습니다. 자세한 내용은 https://surge.sh/ 를 참조합니다.

surge (npm install -g surge)

프롬프트

{} 안의 내용을 원하시는 사이트에 맞게 채워서 사용하세요.

pandoc + shell script 기반의 정적 웹사이트를 만들어줘.

## 프로젝트 개요
Markdown으로 콘텐츠를 작성하고, pandoc으로 HTML 변환 후
Surge로 배포하는 정적 사이트야. Node나 Python 빌드 도구 없이
pandoc과 bash만으로 동작해야 해.

## 디렉토리 구조
- src/content/ : Markdown 원고 파일들 (.md)
- src/template/page.html : pandoc용 HTML 템플릿 ($title$, $body$ 변수 사용)
- src/template/style/ : CSS, 이미지, SVG 등 정적 에셋
- public/ : 빌드 결과물 (.gitignore 대상)

## 빌드 스크립트 (build.sh)
아래 단계를 수행하는 bash 스크립트:
1. public/ 디렉토리를 삭제 후 새로 생성
2. src/template/style/ 을 public/style/ 로 복사
3. src/content/ 에서 .md가 아닌 파일(이미지 등)을 public/으로 복사
4. src/content/*.md 각각에 대해:
   - 첫 번째 "# " 헤딩을 페이지 제목으로 추출
   - pandoc --from markdown --to html --template 으로 HTML 변환
   - 현재 페이지에 해당하는 네비게이션 링크에 class="active" 추가 (sed 활용)

## 배포 스크립트 (publish.sh)
surge ./public {사이트주소} 를 실행하는 한 줄짜리 스크립트.

## HTML 템플릿 (src/template/page.html)
- style/style.css 링크
- 헤더: 사이트 제목 + 아이콘
- 네비게이션 바: 페이지별 링크
- 메인 영역: pandoc의 $body$ 출력
- 푸터

## CSS 디자인 (src/template/style/style.css)
추구하는 룩 & 필:
{여기에 원하는 디자인 방향을 자연어로 기술. 예시:}
{- "따뜻한 느낌의 카페 블로그. 베이지/브라운 톤, 둥근 모서리, 부드러운 그림자"}
{- "미니멀한 기술 블로그. 흰 배경에 검은 글씨, 모노스페이스 폰트, 여백 넉넉히"}
{- "학교 공식 사이트 느낌. 남색 헤더/푸터, 깔끔한 산세리프 폰트"}

공통 요구사항:
- 룩 & 필에 어울리는 웹폰트가 있다면 Google Fonts 등에서 로드
- CSS 변수(custom properties)로 색상 팔레트 정의
- 본문 최대 너비 제한, 중앙 정렬
- 반응형 대응 (모바일에서 폰트/패딩 축소)
- 네비게이션의 hover/active 상태 스타일링

## 콘텐츠 파일
src/content/ 아래에 아래 페이지들의 Markdown을 작성해줘:
{여기에 필요한 페이지 목록과 각 페이지에 담길 내용을 기술. 예시:}
{- index.md : 메인 페이지. 사이트 소개와 공지사항}
{- about.md : 모임 소개}
{- schedule.md : 일정 안내}

Markdown 안의 내부 링크는 .html 확장자를 사용해야 해 (예: about.html).

## 기타
- 페이지 추가 시 page.html의 nav에 수동으로 링크 추가 필요
- .gitignore에 public/ 포함
- CLAUDE.md 파일도 만들어서 프로젝트 구조와 빌드/배포 방법을 기록해줘

GitHub Actions 연동한 Surge.sh 자동 배포

GitHub에 생성된 사이트를 올린다면, GitHub Actions를 통해서 소스가 바뀔 때 자동으로 Surge.sh에 배포를 할 수 있습니다. 저장소의 .github/workflows 아래에 *.yml 파일로 아래 파일을 생성합니다.

name: Build & Deploy to surge.sh

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Install Pandoc
        run: sudo apt-get install -y pandoc

      - name: build
        run: ./build.sh

      - name: Deploy to surge.sh
        uses: dswistowski/surge-sh-action@v1
        with:
          domain: 'your-site.surge.sh'
          project: 'public'
          login: ${{ secrets.SURGE_LOGIN }}
          token: ${{ secrets.SURGE_TOKEN }}

Yml 파일의 your-site.surge.sh에는 원하시는 도메인을 지정하시면 됩니다.

아래 값은 Surge.sh의 인증에 쓰입니다.

로그인 아이디 : ${{ secrets.SURGE_LOGIN }}
인증 토큰 : `${{ secrets.TOKEN }}

토큰 값은 surge token 명령으로 확인하거나 생성할 수 있습니다.

로그인할 이메일과 토큰값을 Action 설정파일에서 참조하기 위해 GitHub 저장소의 Settings -> Secrets and variables > Actions 메뉴에서, Repository secrets 란 아래에서 New repository secret 버튼을 눌러 저장해야합니다. Secret의 'Name'은 SURGE_LOGIN, SURGE_TOKEN으로만 지정하면 됩니다.

benelog/static-site-generation-by-claude.md

Select an option

No results found