HackMD & Astro
HackMD는 협업 Markdown 편집기이자 퍼블리싱 플랫폼입니다. HackMD에서 콘텐츠를 관리하고 Astro 프로젝트에 표시하기 위해 API를 사용할 수 있습니다.
Astro와 통합
섹션 제목: “Astro와 통합”이 가이드는 노트를 가져오기 위해 공식 @hackmd/api 클라이언트를, Markdown 콘텐츠를 렌더링하기 위해 markdown-it을 사용합니다.
전제 조건
섹션 제목: “전제 조건”시작하려면 다음이 필요합니다.
- Astro 프로젝트 - 아직 Astro 프로젝트가 없다면 설치 가이드를 참조하여 즉시 설치하고 실행할 수 있습니다.
- HackMD 계정 - 무료로 가입할 수 있습니다.
- HackMD 액세스 토큰 - HackMD 설정의 API 섹션에서 생성하세요.
- 공개적으로 읽을 수 있는 노트 최소 1개 - 예시가 사이트에 안전하게 게시할 수 있도록 노트의 읽기 권한을 Everyone으로 설정하세요.
자격 증명 설정
섹션 제목: “자격 증명 설정”프로젝트 루트에 .env 파일을 만들고 HackMD 액세스 토큰을 추가하세요:
HACKMD_API_ACCESS_TOKEN=<YOUR_ACCESS_TOKEN>이 변수에 PUBLIC_ 접두사를 붙이지 마세요. 이렇게 하면 토큰이 서버 측 코드에서만 사용 가능하도록 유지되어 Astro가 브라우저에 노출하는 것을 방지할 수 있습니다.
Astro의 환경 변수 및
.env 파일에 대해 자세히 알아보세요.
종속성 설치
섹션 제목: “종속성 설치”HackMD API 클라이언트와 Markdown 렌더러를 설치하세요:
npm install @hackmd/api markdown-itpnpm add @hackmd/api markdown-ityarn add @hackmd/api markdown-itHackMD 구성
섹션 제목: “HackMD 구성”새 src/lib/ 디렉터리에 hackmd.ts 파일을 만드세요. 이 파일은 API 클라이언트를 초기화하고, Markdown을 렌더링하며, 각 노트에 URL 친화적인 식별자를 생성합니다:
import { API } from '@hackmd/api';import MarkdownIt from 'markdown-it';
export const client = new API(import.meta.env.HACKMD_API_ACCESS_TOKEN);
const md = new MarkdownIt({ html: false, linkify: true, typographer: true,});
export function renderMarkdown(content: string) { return md.render(content);}
export function getNoteSlug(note: { permalink: string | null; shortId: string }) { return note.permalink ?? note.shortId;}html: false 옵션은 노트의 원시 HTML이 생성된 페이지에 직접 전달되는 것을 방지합니다. 표준 Markdown은 여전히 HTML로 렌더링됩니다.
프로젝트에서 다음 파일들을 사용합니다:
디렉터리src/
디렉터리lib/
- hackmd.ts
디렉터리pages/
- index.astro
디렉터리notes/
- [slug].astro
- .env
- astro.config.mjs
- package.json
Astro와 HackMD로 블로그 만들기
섹션 제목: “Astro와 HackMD로 블로그 만들기”이 예시는 공개적으로 읽을 수 있는 노트의 인덱스와 각 노트마다 정적으로 생성된 페이지를 만듭니다.
노트 목록 표시하기
섹션 제목: “노트 목록 표시하기”src/pages/index.astro에서 getNoteList()를 사용하여 노트를 가져오세요. 공개 사이트에는 guest 읽기 권한이 있는 노트만 포함되도록 결과를 필터링합니다:
---import { client, getNoteSlug } from '../lib/hackmd';
const notes = await client.getNoteList();const publicNotes = notes.filter((note) => note.readPermission === 'guest');---
<!doctype html><html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width" /> <title>Astro + HackMD</title> </head> <body> <main> <h1>My HackMD notes</h1> <ul> { publicNotes.map((note) => ( <li> <a href={`/notes/${getNoteSlug(note)}/`}>{note.title}</a> </li> )) } </ul> </main> </body></html>