Kinesis

GitHub Pages와 Fuwari로 나만의 기술 블로그 만들기(4)

Tue, 22 Jul 2025 00:00:00 GMT

작업 환경

Ubuntu 22.04

4단계: 개인 도메인 연결하기

이제 개인 도메인을 연결하는 방법에 대해 알아보겠습니다. spaceship 업체로부터 도메인을 구입하여 사용하고 있습니다.

우측에 있는 연결 버튼을 클릭합니다.

이후, 사용자 정의 DNS 레코드 항목을 선택하여 추가합니다.

레코드 추가 -> CNAME 을 선택합니다. 호스트는 blog, 값으로는 github pages 주소를 입력합니다.

이후 Github Pages 에서 Custom domain 을 수정해주면 정상적으로 반영됩니다.

GitHub Pages와 Fuwari로 나만의 기술 블로그 만들기(3)

Tue, 22 Jul 2025 00:00:00 GMT

작업 환경

Ubuntu 22.04

3단계: Github Pages로 배포하기

3.1. 사이트 구축하기

이제 프로덕션 사이트를 구축합니다.

pnpm build # ./dist/에 프로덕션 사이트 구축
pnpm preview # 배포하기 전, 로컬에서 빌드 미리보기

3.2. 사이트 배포하기

이후 정상적으로 빌드가 완료되면 origin에 반영해줍니다.

git add .
git commit -m ":tada: Init: my blog with fuwari template"
git push

이후, commit log를 보면 build가 정상적으로 안 된 것을 알 수 있습니다.

repository Settings -> Pages -> Build and deployment 항목의 Source를 Github Actions 로 설정합니다.

설정을 완료하고, Actions 으로 돌아와서 실패한 build 로그에 진입하여 Re-run jobs 버튼을 클릭합니다. 이후, deploy.yml 파일을 수정합니다. 주석을 제거하고, 들여쓰기 등을 수정한 이후에 다시 commit * push를 진행하면 정상적으로 배포가 되는 것을 확인할 수 있습니다.

:::note 2단계 블로그에서 제공한 yaml 코드를 복사해서 적용했다면 별도로 deploy.yml를 수정하지 않아도 됩니다. :::

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v3

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

정상적으로 배포가 완료된 것을 확인할 수 있습니다.

GitHub Pages와 Fuwari로 나만의 기술 블로그 만들기(2)

Tue, 22 Jul 2025 00:00:00 GMT

작업 환경

Ubuntu 22.04

2단계: 블로그 커스터마이징 및 콘텐츠 작성하기

2.1. 블로그 커스터마이징하기

가장 먼저 블로그의 이름, 설명, 작성자 정보 등을 수정합니다. 대부분의 설정은 src/config.ts 파일에서 관리됩니다.

아래와 같이 정보를 수정합니다.

export const siteConfig: SiteConfig = {
	title: "Kinesis Akashic",
	subtitle: "Datadoll Studio",
	lang: "ko", // 'en', 'zh_CN', 'zh_TW', 'ja', 'ko', 'es', 'th'
	themeColor: {
		hue: 250, // Default hue for the theme color, from 0 to 360. e.g. red: 0, teal: 200, cyan: 250, pink: 345
		fixed: false, // Hide the theme color picker for visitors
	},
	banner: {
		enable: false,
		src: "assets/images/demo-banner.png", // Relative to the /src directory. Relative to the /public directory if it starts with '/'
		position: "center", // Equivalent to object-position, only supports 'top', 'center', 'bottom'. 'center' by default
		credit: {
			enable: false, // Display the credit text of the banner image
			text: "", // Credit text to be displayed
			url: "", // (Optional) URL link to the original artwork or artist's page
		},
	},
	toc: {
		enable: true, // Display the table of contents on the right side of the post
		depth: 2, // Maximum heading depth to show in the table, from 1 to 3
	},
	favicon: [
		// Leave this array empty to use the default favicon
		// {
		//   src: '/favicon/icon.png',    // Path of the favicon, relative to the /public directory
		//   theme: 'light',              // (Optional) Either 'light' or 'dark', set only if you have different favicons for light and dark mode
		//   sizes: '32x32',              // (Optional) Size of the favicon, set only if you have favicons of different sizes
		// }
	],
};

어느정도 수정을 완료하였습니다.

이제 사이트를 정상적으로 배포하기 위한 설정을 진행합니다. astro.config.mjs 파일을 다음과 같이 수정합니다.

site: 도메인 주소(https://<userid>.github.io)

// https://astro.build/config
export default defineConfig({
	site: "https://kinesis19.github.io",
	base: "/",
	trailingSlash: "always",
	integrations: [
		tailwind({
			nesting: true,
		}),

이후, .github -> workflows 에 진입하여 deploy.yml 파일을 생성합니다.

공식문서: configure-a-github-action

공식 문서에저 제공하는 deploy.yml 코드를 복사하여 붙여넣거나 하단에 있는 코드를 복사하여 붙여 넣습니다. (나중에 Github Pages에서 build를 하게 되는데, deploy.yml의 format의 이슈로 하단과 같이 수정하였습니다.)

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v3

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

2.2. 콘텐츠 작성하기

콘텐츠는 마크다운 문법으로 작성할 수 있습니다. Fuwari에서는 마크다운 문법 외에도 다양한 기능을 제공하고 있으니 적절하게 응용하여 콘텐츠 내용을 작성할 수 있습니다.

콘텐츠 작성 예시: Simple Guides for Fuwari

작성을 완료하면 다음과 같이 나타납니다.

GitHub Pages와 Fuwari로 나만의 기술 블로그 만들기(1)

Tue, 22 Jul 2025 00:00:00 GMT

작업 환경

Ubuntu 22.04

1단계: 개발 환경 준비 및 Fuwari 템플릿 설치

1.1. 프로그램 설치

Git: 소스 코드를 관리하고 Github와 연동하기 위한 필수 프로그램입니다.
Node.js: Astro 프로젝트를 실행하기 위한 JavaScript 런타임환경입니다. LTS(Long-Term-Support) 버전을 설치합니다.
- Node.js 공식 홈페이지에서 LTS 버전을 다운로드하여 설치합니다. (2025년 7월 14일 기준 v20 이상의 버전을 사용해야 합니다.)
pnpm: Fuwari 템플릿을 사용하기 위해 필요한 패키지 관리자입니다.
- pnpm 공식 홈페이지에서 자신의 운영체제에 맞는 버전을 다운로드하여 설치합니다. (2025년 7월 14일 기준 v9 이상의 버전을 사용해야 합니다.)

설치 확인은 terminator에서 다음 명령어를 입력하여 버전 정보가 나오는지 확인합니다.

git --version
node --version
npm --version
pnpm --version

이후 Fuwari 공식 README.md에서 명시된 버전을 준수하였는지 확인합니다.

1.2. Fuwari 템플릿 fork & run

Fuwari 공식 repository에서 우측 상단에 있는 Fork 버튼을 클릭합니다.

Repository name: 생성할 repository(저장소)의 이름입니다. Github에서 Github Pages 기능을 제공하기에 <username>.github.io 형식으로 설정하는 것을 추천합니다.
Description: repository의 설명을 작성합니다.

모든 설정을 완료했다면, 좌측 하단에 있는 Create fork 버튼을 클릭합니다.

fork한 repository에서 Code 버튼을 클릭하고, 현재 repository의 Web URL을 복사합니다. 복사한 URL은 다음과 같은 형식으로 구성되어 있습니다.

https://github.com/kinesis19/kinesis19.github.io.git

Terminator을 실행하고, fork한 repository를 clone하고, 해당 경로로 진입합니다.

git clone https://github.com/kinesis19/kinesis19.github.io.git # clone
cd kinesis19.github.io # 경로 진입

이후, 블로그 개발에 필요한 라이브러리(패키지)들을 설치합니다.

pnpm install

로컬 개발 서버를 시작합니다.

pnpm dev

화면에 나타난 Local address를 Ctrl + Left Click 혹은 인터넷 브라우저에 입력하여 진입합니다.

정상적으로 개발 환경이 구축된 것을 알 수 있습니다.

GitHub Pages와 Fuwari로 나만의 기술 블로그 만들기(5)

Tue, 22 Jul 2025 00:00:00 GMT

작업 환경

Ubuntu 22.04

5단계: 댓글 기능 추가하기

다양한 서드파티 중에 Giscus를 사용해서 댓글 기능을 추가하겠습니다.

5.1. Giscus 서드파티 추가하기

먼저 Giscus를 추가하기 위한 조건을 확인합니다.

1번째 조건은 이미 충족 되었으니, 2번째 조건인 Giscus를 설치합니다. Giscus 설치하기

Install 버튼을 클릭합니다.

이후, Only select repositories를 선택하고, blog로 사용하고 있는 repository를 할당합니다.

정상적으로 추가된 것을 알 수 있습니다.

이후 repository의 settings에 들어가서 Discussions -> Set up discussions를 클릭합니다.

우측 하단에 있는 Start discussion 버튼을 클릭하고, Start discussion 버튼을 클릭해서 설정해 주면 됩니다.

다시 Giscus 설정 페이지로 돌아와서 저장소 주소를 할당합니다.

5.2. 블로그에 Giscus 추가하기

그대로 사용해도 되고, 취향껏 커스터마이징을 진행합니다. 하단에 생성된 Giscus 관련 <script> 관련 코드를 복사합니다.

그 다음에 repository의 src/components/ 경로에서 Giscus.astro 파일을 하나 추가합니다. 이후, Giscus 페이지에서 복사한 <script> 코드를 다음과 같이 붙여 넣습니다.

---
// src/components/Giscus.astro
---
<div class="giscus-container">
    <script src="https://giscus.app/client.js"
        data-repo="kinesis19/kinesis19.github.io"
        data-repo-id="R_kgDOPMN3mw"
        data-category="General"
        data-category-id="DIC_kwDOPMN3m84CtQ1D"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="ko"
        crossorigin="anonymous"
        async
    >
    </script>
</div>

이후 pages/posts/ 경로에 있는 [...slug].astro 파일의 코드를 수정합니다.

import문 추가

---
// pages/posts/[...slug].astro
---
import path from "node:path";
import License from "@components/misc/License.astro";
import Markdown from "@components/misc/Markdown.astro";
import I18nKey from "@i18n/i18nKey";
import { i18n } from "@i18n/translation";
import MainGridLayout from "@layouts/MainGridLayout.astro";
import { getSortedPosts } from "@utils/content-utils";
import { getDir, getPostUrlBySlug } from "@utils/url-utils";
import { Icon } from "astro-icon/components";
import { licenseConfig } from "src/config";
// 아래와 같이 Giscus import
import Giscus from "../../components/Giscus.astro";
import ImageWrapper from "../../components/misc/ImageWrapper.astro";
import PostMetadata from "../../components/PostMeta.astro";
import { profileConfig, siteConfig } from "../../config";
import { formatDateToYYYYMMDD } from "../../utils/date-utils";

Giscus 태그 추가

            <Markdown class="mb-6 markdown-content onload-animation">
                <Content />
            </Markdown>

            {licenseConfig.enable && <License title={entry.data.title} slug={entry.slug} pubDate={entry.data.published} class="mb-6 rounded-xl license-container onload-animation"></License>}
            <!-- Add Giscus -->
            <Giscus />

        </div>
    </div>

수정한 내용을 저장하고 local 서버를 실행하면, 정상적으로 반영된 것을 알 수 있습니다.

Trouble Shooting

T1. Run Biome issue

Run biome ci ./src --reporter=github
  biome ci ./src --reporter=github
  shell: /usr/bin/bash -e {0}
Error: The imports and exports are not sorted.
ci ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  × Some errors were emitted while running checks.
  

Error: File content differs from formatting output
Error: Process completed with exit code 1.

위와 같이 Run biome 관련해서 build 실패가 확인되면 다음 명령어를 통해 해결하고, 다시 push하면 정상적으로 build 됩니다.

pnpm run lint