Hugo로 매뉴얼 만들기 #1 설치부터 첫 문서까지

프레임워크 Hugo Documentation Static Site
4 분 소요

문서를 처음 체계적으로 만들다 보면 거의 예외 없이 같은 문제를 만납니다. README 한 장으로는 감당이 안 되는 문서를 어디에 쌓을 것인가 하는 문제입니다. 노션은 외부 공개와 버전 관리가 번거롭고, 블로그 도구로 만들면 글이 시간순으로 나열될 뿐 레퍼런스로 쓰기 불편합니다. 그래서 많은 팀이 문서를 코드처럼 다루는 방식, 곧 Docs as Code로 옮겨 갑니다. 마크다운으로 쓰고, Git으로 관리하고, 정적 사이트로 배포하는 방식입니다.

이 시리즈는 그 첫 단추인 정적 사이트 생성기로 문서 사이트를 짓는 법을 다룹니다. 도구는 Hugo입니다. Go로 만들어진 단일 바이너리라 설치가 가볍고, 빌드가 수백 페이지에서도 1초 안팎으로 끝납니다. 테마는 문서에 특화된 Hextra를 씁니다.

이번 시리즈는 Hugo로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지 ← 이번 글
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, 콜아웃
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색 색인, 접근성, 문서 문화

이번 글은 Hugo가 무엇을 준비물로 요구하는지, 그리고 새 사이트를 만들어 Hextra를 붙이고 로컬에서 첫 문서를 띄우는 데까지를 직접 실행해 보며 마무리하겠습니다.

준비물 세 가지 #

Hugo 문서 사이트는 도구 세 개를 먼저 깔아야 합니다.

  1. Hugo Extended — Hugo는 일반판과 Extended 두 가지가 있습니다. Hextra를 비롯한 최신 테마는 내장 에셋 처리 기능을 쓰기 때문에 반드시 Extended를 설치해야 합니다.
  2. Go — Hextra는 Hugo Modules로 배포됩니다. 테마를 내려받고 갱신하는 데 Go가 필요합니다.
  3. Git — Hugo Modules가 내부적으로 Git을 사용하고, 어차피 문서를 Git으로 관리할 것이라 함께 준비합니다.

Hugo 설치 #

운영체제별 명령은 다음과 같습니다.

설치 (macOS / Windows / Linux) 
# macOS (Homebrew)
brew install hugo go git

# Windows (winget)
winget install Hugo.Hugo.Extended GoLang.Go Git.Git

# Linux (예: Debian, Ubuntu 계열은 배포판 패키지가 오래된 경우가 많아
# 공식 릴리스 바이너리 설치를 권장)
sudo apt install golang-go git
# Hugo Extended는 GitHub 릴리스의 hugo_extended_*.deb 내려받아 설치

설치 후 버전을 확인합니다. 출력에 extended가 들어 있어야 합니다.

버전 확인 
hugo version
# hugo v0.xxx.x+extended ... 처럼 extended 표기 확인
go version

extended가 보이지 않으면 일반판이 깔린 것이라, Extended로 다시 설치해야 다음 단계에서 막히지 않습니다.

새 사이트 만들기 #

빈 사이트를 하나 생성합니다. 설정 파일 형식은 읽기 편한 YAML로 지정하겠습니다.

새 사이트 생성 
hugo new site my-docs --format yaml
cd my-docs

생성된 폴더에서 Hugo Modules를 초기화합니다. 뒤의 경로는 나중에 이 저장소를 올릴 위치로 적어 두면 됩니다. 당장 정확하지 않아도 동작에는 지장이 없습니다.

모듈 초기화 
hugo mod init github.com/내계정/my-docs

Hextra 테마 연결 #

설정 파일 hugo.yaml을 열고 Hextra를 모듈로 가져오도록 작성합니다.

hugo.yaml 
# hugo.yaml
baseURL: "https://example.com/"
title: 제품 매뉴얼
languageCode: ko

module:
  imports:
    - path: github.com/imfing/hextra

그다음 테마 모듈을 내려받습니다.

테마 내려받기 
hugo mod get github.com/imfing/hextra

테마를 Git 서브모듈로 복사해 넣는 옛 방식과 달리, 모듈 방식은 버전을 명령 한 줄로 올리고 내릴 수 있어 관리가 깔끔합니다.

첫 문서 띄우기 #

이제 문서를 한 장 만듭니다. 먼저 첫 화면이 될 content/_index.md입니다.

content/_index.md 
---
title: 제품 매뉴얼
---

우리 팀의 공식 문서입니다. 왼쪽 사이드바에서 항목을 골라 보세요.

이어서 실제 문서 한 편을 추가합니다.

문서 생성 
hugo new content docs/getting-started.md

생성된 파일을 열어 본문을 채웁니다.

content/docs/getting-started.md 
---
title: 시작하기
---

## 설치

다음 명령으로 설치합니다.

```bash
npm install our-product
```

마지막으로 로컬 서버를 띄웁니다. 초안 상태 문서까지 함께 보려면 -D 옵션을 붙입니다.

로컬 서버 실행 
hugo server -D

브라우저에서 http://localhost:1313을 열면 Hextra 기본 레이아웃에 방금 만든 문서가 사이드바와 함께 나타납니다. 파일을 수정하고 저장하면 화면이 자동으로 새로고침됩니다.

폴더 구조 이해하기 #

지금까지 만들어진 구조에서 당장 알아야 할 것은 content 한 곳입니다.

폴더 구조 
my-docs/
├─ hugo.yaml        # 사이트 설정
├─ content/         # 문서 본문 (여기만 채우면 됩니다)
│  ├─ _index.md     # 첫 화면
│  └─ docs/
│     └─ getting-started.md
├─ static/          # 이미지 등 그대로 제공할 파일
└─ go.mod           # 모듈 목록 (Hextra 의존성 기록)

문서를 늘리는 일은 결국 content 아래에 마크다운 파일을 더하는 일입니다. 폴더 구조가 그대로 사이드바의 위계가 됩니다. 이 점이 블로그 도구와 가장 다른 부분이고, 다음 편에서 본격적으로 다룰 내용입니다.

마무리 #

이번 글에서는 Hugo Extended와 Go를 설치하고, 새 사이트에 Hextra를 붙여 로컬에서 첫 문서를 띄우는 데까지 마쳤습니다. 아직은 기본 골격뿐이지만, 마크다운 파일 하나가 곧바로 검색 가능한 문서 페이지가 된다는 흐름은 확인했습니다.

다음 편에서는 사이드바 구성과 검색을 다룹니다. 문서가 수십 편으로 늘어도 독자가 길을 잃지 않도록 정보 구조를 설계하는 단계입니다.

X