Hugo + Netlify + CMS 블로그 만들기

나는 2020년(대학교 3학년) 코로나 팬데믹으로 개강이 늦춰지자 예전부터 만들고 싶던 블로그를 한 달 동안 만들고자 했다. 그래서 난 고2 때 배운 얕은 html,css,js,php와 웹프로그래밍 전공 수업의 지식 ~~(사실 웹은 프로그래밍이 아니다.)~~ 등으로 블로그를 만들려고 완전 아무것도 없는 파일에 한 줄씩 써 내려가면서 만들었다.

하지만 웹에 대해 매우 잘 아는 것도 아니기에 내가 필요한 기능을 구현해 내기란 정말 어려웠다. 사실 가장 초창기에는 웹을 파티션으로 나눠서 만든다고 생각을 못해서 페이지마다 수정이 일어나면 전체적으로 수정을 했기에 더 삽질했던 것 같다.

그러던 찰나 정적 웹 생성기를 알게 되었다. 그중에서도 Hugo ~~(당시 가장 Hot한 언어인 Go언어로 만들어졌다길래 Go언어도 배울 겸 시작한 건데 Go랑은 전혀 상관이 없다)~~ 를 택했고 바로 기존에 작업하던 것을 모두 옮겼다. 하지만 신생 언어라 한글 레퍼런스는 찾을 수 없어 매우 힘들었다.

아래 그림은 그때 내가 겨우 손수 제작한 첫 블로그이다. 나름 디자인도 열심히 하고 기능도 추가하며 밤새 작업했지만, 하나 수정하면 다른 곳에서 생겨나는 버그 때문에 포기했다. 그리고 1년이 지난 지금 철저한 설계, 사전 조사 및 계획, 벤치마킹으로 드디어 블로그 제작에 성공했다.

첫 번째 블로그 디자인

Hugo, 세상에서 가장 빠른 정적 웹사이트 생성기

정적 웹사이트 대해서 자세히 다루지는 않겠다. 간단하게 설명하자면 미리 웹사이트를 만들어 놓고 클라이언트의 요청 시 바로바로 전달해준다고 생각하면 된다.

Hugo를 선택한 이유

다른 유명한 정적 웹사이트 생성기는 Jekyll, Gatsby가 있다. 사실 자료와 예제가 많은 것이 개발하는데 훨씬 편하지만 나는 속도를 첫 번째 중요하게 여겼다. Hugo는 Go언어로 제작되었기 때문에 Jekyll의 Ruby, Gatsby의 React보다 훨씬 속도가 빠르다. 그리하여 단순히 Hugo를 선택하게 되었다.

Hugo 설치

Window package 기준으로 설명하겠다. 자세한 내용은 Hugo Quick Start 에 나와있다.

Package management(Chocolatey) 설치
- Window PowerShell(관리자) 실행 후 명령어 실행

1
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Golang 설치
- Hugo는 Go언어로 동작하니 당연히 Go를 설치 해야한다.

1
choco install golang

Git 설치
- Github에서 Theme 설치하기 위해 필요하다.
- 이 포스팅에서는 Git과 Github의 기본적인 사용을 할 줄 안다는 가정하에 작성 되었습니다.

1
choco install git

Hugo 다운
- 일반버전과 Extended 두 가지 버전이 있지만, Extended 버전이 기능이 더 많으므로 hugo-extended 설치

1
choco install hugo-extended -confirm

설치가 완료되면 이제부터 Hugo를 이용해서 나만의 정적 웹사이트를 제작할 수 있다.

Hugo 시작하기

프로젝트 폴더 만들기

원하는 폴더 위치에서 다음 명령어를 실행하면 프로젝트 폴더가 생성된다.
project-name에 원하는 프로젝트명을 넣으면 된다.

1
hugo new site project-name

명령어가 수행되면 프로젝트 폴더 생성과 함께 초기화 되어있다.
초기 프로젝트 폴더 구조는 다음과 같다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
cd project-name
tree /F
.
├─config.toml
├─archetypes
│   └─default.md
├─content
├─data
├─layouts
├─static
└─themes

6개의 빈 폴더와 1개의 config.toml이 생성된다.
- archetypes - hugo new 파일이름 명령어로 content 생성시 content type에 따른 기본 Front Matter값을 정해주는 파일이 저장된 폴더.
- content - 웹사이트에 표시될 모든 글들이 저장된 폴더. 여기에 저장된 모든 파일은 웹사이트의 페이지가 된다.
- data - 편하게 사용하고 싶은 데이터들을 저장할 수 있는 폴더. json, toml, yaml, csv 등의 파일들로 저장하고 불러와서 사용할 수 있다.
- layouts - 웹사이트에 실제로 적용되는 html 구조를 저장하는 폴더. 페이지 형식이나 sidebar와 같은 기능을 넣을 수도 있다.
- static - build 후 이 폴더 안의 파일은 모두 그대로 옮겨진다. 이미지, JS, CSS 등을 저장하는 폴더.
- themes - git으로 이미 제작된 테마를 다운받아 저장하는 폴더.
- config.toml - 웹사이트에 대한 기본 정보들을 저장하는 파일.

Hugo 개발환경이 모두 갖춰졌지만 이 글에서는 Hugo 코딩 방법을 기술하지는 않겠다. 계속 검은 화면만 보고 있으 아무것도 한게 없어보이니 테마를 적용해보자.

Hugo는 폴더와 파일구조 형식만 맞으면 테마를 언제든지 교체할 수 있다. 즉, 마음에 안들거나 원하는 테마가 생기면 기존의 웹 페이지는 건들지 않고 테마만 적용하면 된다.

난 여러 주제의 카테고리를 깔끔하게 분류하고 가독성 높은 블로그를 원하였기에 여러 테마를 짜깁기 해서 나만의 테마를 구성하였다.

테마 적용하기

일단 프로젝트 폴더에 다음 명령어로 git을 생성한다.

1
git init

먼저 자신이 마음에 드는 테마를 Hugo Themes에서 고르자.
계속 새로운 테마들이 등록 되며, 기존의 테마들도 계속 업데이트가 된다.

Coder Themes

깔끔해 보이는 Coder Themes를 선택했다. Demo 버튼을 누르면 실제로 테마가 어떻게 적용되는지 체해 볼 수 있다.
Download 버튼을 누르면 해당 Github 페이지로 연결된다. 이 Github 페이지를 복사해두고 다음과 같이 입력한다.

1
git submodule add https://github.com/luizdepra/hugo-coder.git ./themes/hugo-coder

Git Submodule이란?
하나의 프로젝트안에 다른 Git 프로젝트를 별개로 관리하면서 프로젝트에서는 공통으로 사용할 수 있는 기능이다.

이제 themes 폴더로 이동해보면 hugo-coder 테마가 설치된 것을 확인 할 수 있다.
테마 폴더에 있는 exampleSite 폴더 안의 파일들을 모두 프로젝트 폴더에 복사하고 프로젝트 폴더에서 다음 명령어를 입력하고 웹 브라우저에서 localhost:1313에 접속하면 테마가 적용된 웹페이지를 확인 할 수 있다.

1
2
3
hugo server
or
hugo server -D

-D 옵션을 추가하면 draft 문서도 확인 할 수 있는 옵션인데, draft는 작업 중인지 아닌지를 나타내는 특성으로 Front Matter에 포함되어있다. draft=true로 되어있으면, 해당 옵션을 넣었을 때 이 페이지도 포함해서 보여주지만 이후 빌드 과정에서는 제외하고 생성된다. 따라서 작업을 완료하게 되면 draft=true 부분을 지우면 된다.

Example Page

테마 Custom 하는 방법은 다른 포스팅에서 다루겠다.

Web 호스팅

이제 인터넷을 통해 웹사이트를 접속하기 위해서는 호스팅이 필요하다. 호스팅 방법으로는 본인의 컴퓨터나 NAS에서 서버를 돌리는 방법과 호스팅 해주는 기업에 호스팅 할 수 있다.

나는 이전에 내 컴퓨터로 서버를 구축해서 블로그를 호스팅 하였는데 컴퓨터를 항상 켜 놓아야 한다는 단점 때문에 호스팅 할 수 있는 기업을 찾아보았다.

먼저 github에 hugo를 저장하기 때문에 git으로 연동이 되고 Repository가 수정 될 때마다 자동으로 블로그에 반영되고 일단 무료로 시작 할 수 있는 호스팅 서비스를 찾다가 Netlify라는 호스팅 서비스를 발견하였다.

Git & Netlify 연동

Netlify Deploy

먼저 프로젝트 폴더 하위에 nelitfy.toml 파일을 추가하고 Github에 push 한다.

📃 netlify.toml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
[build]
  publish = "public"
  command = "hugo --gc --minify"

[context.production.environment]
  HUGO_VERSION = "0.79.0"
  HUGO_ENV = "production"
  HUGO_ENABLEGITINFO = "true"

[context.split1]
  command = "hugo --gc --minify --enableGitInfo"

[context.split1.environment]
  HUGO_VERSION = "0.79.0"
  HUGO_ENV = "production"

[context.deploy-preview]
  command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"

[context.deploy-preview.environment]
  HUGO_VERSION = "0.79.0"

[context.branch-deploy]
  command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"

[context.branch-deploy.environment]
  HUGO_VERSION = "0.79.0"

[context.next.environment]
  HUGO_ENABLEGITINFO = "true"

이후 Netlify에 접속하여 본인이 사용하는 Git을 이용해 가입한다.

Netlify Page

Git 및 Repository의 접근 제한 승인을 허용한다.

Create a New site

Git을 사용하여 Repository에 Push해야만 다음과 같은 화면이 나온다.
나는 JuneLog라는 Repository에 저장하였으며 본인의 Hugo Repository를 선택한다.
Repository가 보이지 않는다면 add로 Repository를 추가한다.

Repository 연동

계속 진행하면 다음과 같은 화면이 나온다.
Branch to deploy에 main을 선택하고(main이 없다면 master) Build command 는 hugo, Publish directory 는 /public을 입력하고 Deploy site 버튼을 클릭하면 호스팅이 시작된다.

Site Settings

이제부터는 github에 해당 Repository에 push 할 때 마다 자동적으로 Netlify에서 build 후 deploy 해주기 때문에 호스팅 과정은 신경 쓰지 않아도 된다.
Repository에 push하면 Production deploys 탭에서 build 되는 과정을 확인 할 수 있으며, 해당 Production을 클릭하면 build와 deploy log로 오류가 없는지 확인 할 수 있다.
build가 끝나고 Published로 변경되면 URL에 자동으로 반영된 것을 확인 할 수 있다.

URL 변경

초기 생성 시 영어와 숫자로 조합된 ~.netlify.app 주소로 생성된다. 해당 페이지를 클릭하면 해당 URL에 호스팅 되는 것을 확인 할 수 있다.

Deploy Site

초기에 생성되는 URL이 마음에 들지 않을 때 netlify.app 앞 부분은 사용자가 임의로 커스텀 할 수 있다.
먼저 Site settings 버튼을 클릭한다.

Site settings

그리고 Site information 탭에서 Change site name 버튼을 클릭하면 Site name을 변경 할 수 있는 창이 나온다.

Site information Tab

Site name에 원하는 URL 이름을 적고 Save 버튼을 누르면 바로 즉시 변경한 URL 적용된다.

Site information Tab

Content Management System

Content Management System(이하 CMS)를 이번 블로그를 준비하면서 처음 알게 되었다. 원래 넣을 생각이 없었지만 ~~(사실 이런게 존재하는지도 모르고 내가 직접 만들려고 했다)~~, 너무 필요한 기능 같아서 여러 CMS 서비스를 찾아보았다.

Hugo에서는 Markdown으로 글을 적기 때문에 글을 작성하거나 관리하기 불편하고 Local Repository가 있는 컴퓨터에서만 작성할 수 있는 단점이 있다. 그래서 이러한 점을 보완하기 위해 CMS를 사용하면 글을 인터넷만 연결되면 웹에서 작성할 수 있고 글 관리나 작성되고 있는 포스팅이 어떻게 나올지 미리 확인하면서 작성할 수 있다.

CMS 종류에는 여러가지가 있지만 나는 Front는 Hugo 생성기를 이용해서 제작하기 때문에 Headless CMS인 Backend만 지원하는 CMS(Contentful, Ghost, Strapi, forestry, Netlify CMS) 중 무료로 지원하는 기능이 많은 Netlify CMS를 선택하였다. ~~(사실 Contentful을 사용하고 싶었지만 정보가 부족하고 잘 적용이 안되었다.)~~

Netlify 적용하기

공식 페이지(Netlify CMS)를 보면, Hugo는 /static 폴더에 다음과 같은 추가 파일 구조를 만들어야한다.

1
2
3
admin
├ index.html
└ config.yml

/static 폴더에 admin 폴더를 생성하고 index.html과 config.yaml 파일 만든다.

📃 index.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
</head>
<body>
  <!-- Include the script that builds the page and powers Netlify CMS -->
  <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
  <script>
    if (window.netlifyIdentity) {
      window.netlifyIdentity.on("init", user => {
        if (!user) {
          window.netlifyIdentity.on("login", () => {
            document.location.href = "/admin/";
          });
        }
      });
    }
  </script>
</body>
</html>

📃 config.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
backend:
  name: git-gateway
  branch: main

publish_mode: editorial_workflow

media_folder: "/static/img/uploads"
public_folder: "/img/uploads"

collections:
  - name: "posts"
    label: "Posts"
    folder: "content/post"
    create: true
    slug: "{{slug}}"
    fields:
      - {label: "Layout", name: "layout", widget: "hidden", default: "posts"}
      - {label: "Title", name: "title", widget: "string"}
      - {label: "Author", name: "author", widget: "string"}
      - {label: "Publish Date", name: "date", widget: "datetime"}
      - {label: "Description", name: "description", widget: "string"}
      - {label: "Tags", name: "tags", widget: "list"}
      - {label: "Body", name: "body", widget: "markdown"}

config.yaml 파일은 CMS의 글 작성 양식을 설정하는 파일이다. 이 포스팅에서는 설정 방법을 다루지 않겠다. 해당 부분은 Configuration Options 에서 찾아 볼 수 있다.
이제 Netlify로 접속하여 Identity 탭에 접속해서 Enable Identity 버튼을 눌러 활성화 한다.
그리고 Registration 탭에서 External providers에 Github을 추가하여 Github 계정으로 로그인 할 수 있게 설정해준다.

External providers

그리고 Services 탭에 있는 Git Gateway에서 Enable Git Gateway 버튼을 눌러 활성화 시킨다.

Git Gateway

그리고 /static 폴더에 있는 index.html의 body부분에 다음 코드를 삽입한다.
이 코드를 넣어야 Github 계정으로 로그인 할 수 있다.

1
<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>

push 후 https://웹주소.netlify.app/admin로 접속하면 로그인 할 수 있는데 Github Login 버튼으로 로그인을 진행하면 된다.
🚨 로그인 할 때 Git Gateway Error 가 발생하면 해당 페이지의 관련 Cache를 모두 제거하고 진행하면 잘된다.

로그인이 완료 되면 다음과 같은 화면을 볼 수 있는데 New Posts 버튼을 눌러 글을 작성 할 수 있다.
글을 작성후 Save 버튼을 누르면 자동으로 Repository에 Commit이 되고 Publish 버튼을 누르면 Pull Request 되어 Netlify에서 감지하고 자동으로 Deploy까지 해준다.

Content Manager

그리고 다시 Registration 탭에서 Open을 Invite only로 수정해야 본인만 글을 작성 할 수 있다.

Registration preferences

🚩 반드시 Continue with GitHub로 로그인한 후에 Invite only로 수정해야 한다.

🚨 Continue with Github 로그인이 안되는 경우

간혹 Instance 오류로 로그인이 안되는 경우가 발생한다. 이때는 Identity 탭을 눌러 Invite users 를 클릭하여 이메일을 적고 Send 버튼을 눌러준다.

그럼 해당 이메일로 인증 메일이 도착 하였을 것이다. Accept the invite 를 클릭하면 블로그로 이동한다.
URL을 확인해보면 ~.netlify.app/#invite_token=~ 으로 #invite_token이 붙어 있다.
app/과 #invite_token 사이에 admin을 넣어 ~.netlify.app/admin#invite_token=~으로 접속하여 비밀번호를 설정하는 창이 나온다. 그럼 비밀번호를 설정하고 로그인을 하면 정상적으로 접속 할 수 있다.

🦉 마무리 🦉

이 포스팅은 처음으로 Netlify CMS 으로 작성한 글이다. 해당 기능으로 글을 작성해본 결과 여러가지 버그가 존재하였다.

한글로 글을 작성하다 보면 간혹 글이 씹히는 경우가 발생한다. 그래서 정신 안 차리고 글을 작성하면 글자가 군데군데 빠져있다.
어떤 이유인지 모르겠지만 Save 기능과 Publish 기능이 먹통이 된다. 먹통 될 뿐만 아니라 글이 통째로 사라져 Rollback 하는 상황이 발생 하기도 하였다.

이 두 가지를 제외하고는 갓 시작하는 블로그에서는 크게 불편한 점은 없는 것 같다. 그래도 무료로 제공하는 기능으로는 부족하다면 Ghost나 다른 Headless CMS로 바꿀 생각이다.