정적 사이트 artifact 만들기
정적 사이트 artifact는 현재 Binder의 Markdown, 구조, 사이트 설정과 공개 가능한 resource를 브라우저가 바로 읽을 수 있는 파일 묶음으로 변환한 파생 결과다. 인터넷에 게시하는 단계와는 다르다. 로컬 정적 결과가 정상이어도 provider 연결, domain, DNS와 원격 배포는 별도로 확인해야 한다.
이 장에서는 예제 Binder로 정적 결과를 만들고 index.html, 문서 route, asset, link와 원본 보존을 검사한다.
먼저 구분할 세 가지
| 대상 | 역할 | 원본인가 |
|---|---|---|
| Binder | Markdown과 asset을 보관하고 편집하는 source | 예 |
| 정적 artifact | Hugo가 만든 HTML·CSS·JavaScript·image 결과 | 아니오 |
| 게시된 사이트 | 정적 artifact를 provider나 server에 올린 결과 | 아니오 |
artifact 안의 HTML을 직접 수정하면 다음 빌드에서 사라진다. 수정이 필요하면 Markdown, frontmatter, Binder 구조 또는 Site 설정을 고친 뒤 다시 만든다.
실습 Binder 준비
Output Artifact Lab 예제 전체를 별도 폴더로 복사하고 Scope로 연다.
| 파일 | 목적 |
|---|---|
01_output-brief.md |
세 출력 형식과 공통 source를 설명하는 본문 |
02_release-checklist.md |
정적·package·PWA 결과 검증표 |
assets/output-mark.svg |
asset 복사와 상대 경로 확인용 SVG |
README.md |
전체 재현 순서와 안전 경계 |
복사본을 쓰면 출력 전후 Markdown 해시를 비교할 수 있고 .glif의 파생 publish 상태도 실습마다 분리할 수 있다.
출력 전에 사이트 설정 확인
- 상단 출력을 연다.
- 왼쪽 앱처럼 설치 또는 Web 패키지가 아니라 먼저 정적 사이트·미리보기 항목을 확인한다.
- 오른쪽 Site 설정에서 제목, 언어, 목차 깊이와 접근 모드를 확인한다.
- base URL을 사용할 배포 주소에 맞춘다. 로컬 검사만 할 때도 절대 URL이 필요한 canonical·sitemap 결과를 고려한다.
- 메뉴에서 빠질 section과 공개하면 안 되는 파일이 없는지 확인한다.
- 설정을 저장한 뒤 게시 전 점검이 준비됨인지 확인한다.
화면에 hugo.toml 파일을 찾을 수 없습니다가 보이면 아직 이 Binder에 Site 설정이 만들어지지 않은 상태다. 기본 게시 값을 적용하거나 Site 설정을 한 번 저장한 뒤 다시 검사한다. 다른 Binder에서 가져온 설정을 그대로 복사하기보다 현재 Binder의 title·language·base URL을 명시한다.
출력 구조 결정하기
정적 사이트의 route는 파일 이름만으로 결정되지 않는다. 다음 입력이 함께 작동한다.
- Binder의 section folder와
_index.md - Markdown 문서의 상대 경로
- frontmatter의 title, slug, weight와 공개 상태
- 출력 구조에서의 포함·제외와 순서
- Site 메뉴 설정
- base URL과 언어 설정
예제에서는 01_output-brief.md와 02_release-checklist.md가 서로 독립된 문서 route가 된다. README.md를 공개 문서로 사용할지 운영 메모로 제외할지는 출력 구조에서 명시한다. assets/output-mark.svg는 문서 링크가 가리키는 정적 resource로 남아야 한다.
정적 결과 만들기
- 출력 대상이 현재 Binder인지 확인한다.
- 구조 목록이 현재 Binder의 Markdown을 가리키는지 확인한다.
- 제외할 문서를 끄고, 남은 문서 순서를 확정한다.
- Site 설정을 저장한다.
- 미리보기 적용 또는 정적 사이트 빌드를 실행한다.
- 실행 중 Binder를 바꾸거나 source 파일을 이동하지 않는다.
- 완료 뒤 결과 폴더의
index.html과 생성 파일 수를 확인한다.
빌드는 source를 다른 형식으로 물질화하는 과정이다. 화면에 보이는 editor tab만 저장하는 동작이 아니며, 열지 않은 문서와 연결된 asset도 출력 구조에 따라 포함될 수 있다.
결과 폴더에서 확인할 것
최소한 다음 항목을 직접 확인한다.
| 검사 | 통과 기준 |
|---|---|
| 시작 문서 | 결과 root에 index.html이 있다 |
| 문서 route | 포함한 각 문서가 예상 URL로 열린다 |
| asset | SVG·image·font가 404 없이 표시된다 |
| 내부 link | 상대 link가 결과 route를 가리킨다 |
| 외부 link | protocol과 대상 주소가 유지된다 |
| 메뉴 | section 이름과 순서가 Site 설정과 같다 |
| 검색 | 포함 문서만 검색 결과에 나타난다 |
| 언어 | HTML 언어와 표시 문구가 설정과 같다 |
| canonical | base URL이 임시 주소로 남지 않는다 |
| 원본 | Markdown 내용과 해시가 빌드 전후 같다 |
성공 알림만으로 통과 처리하지 않는다. 결과 폴더에서 파일을 세고, 브라우저에서 시작 route와 적어도 한 하위 route를 직접 연다.
로컬 미리보기와 배포 결과의 차이
로컬 미리보기는 route와 화면을 빠르게 검사하기 좋지만 다음 항목을 대신하지 않는다.
- 실제 custom domain과 HTTPS
- provider의 redirect·header 규칙
- 원격 cache와 purge
- analytics 수집 동의와 전송 여부
- 외부 embed의 CSP·network 정책
- 배포 credential과 권한
따라서 정적 artifact가 통과하면 배포 가능한 입력이 준비된 것이지, 인터넷 게시가 완료된 것은 아니다.
원본 보존 확인
출력 전후 다음 파일을 비교한다.
_index.md
README.md
01_output-brief.md
02_release-checklist.md
assets/output-mark.svg정적 빌드는 이 source를 고치지 않아야 한다. publish staging, public과 cache는 파생 상태이며 source 목록에 섞지 않는다. 결과 HTML을 Binder로 다시 가져와 원본처럼 편집하는 흐름도 아니다.
예상과 다를 때
시작 화면이 없다
- 결과 root의
index.html존재 여부를 확인한다. _index.md와 home output 설정을 확인한다.- destination을 이전 빌드 폴더와 혼동하지 않았는지 확인한다.
문서가 빠졌다
- 출력 구조의 제외 상태를 확인한다.
- Markdown 확장자와 숨김 folder 정책을 확인한다.
- 현재 구조 snapshot이 다른 Binder에서 남은 것이 아닌지 새로고침한다.
image 또는 SVG가 깨진다
- Markdown 링크가 Binder 상대 경로인지 확인한다.
- 파일 이름의 대소문자 차이를 확인한다.
- source 밖의 절대 경로를 참조하지 않았는지 확인한다.
route는 열리지만 style이 없다
- base URL과 상대 asset URL을 확인한다.
- theme·static resource가 출력 폴더에 포함됐는지 확인한다.
file://로 직접 열지 말고 로컬 HTTP server로 검사한다.
이번 실증에서 확인한 범위
release candidate 앱에서 PB-02 예제 source 4개 항목을 읽고 번들 Hugo로 정적 결과를 만들었다. 결과는 index.html을 포함해 39개 파일이었고, 다섯 fixture 파일의 결합 SHA-256은 출력 전후 동일했다.
이 증거는 로컬 정적 결과 생성과 source 보존을 확인한다. 실제 provider 배포, custom domain, 외부 network와 모든 브라우저 호환성까지 주장하지 않는다.
다음으로 Folio 실행 패키지와 PWA에서 같은 정적 결과를 단일 실행 파일과 설치 가능한 공개 사이트로 사용하는 방법을 이어서 확인한다.