HackMD & Astro

HackMD는 협업 Markdown 편집기이자 퍼블리싱 플랫폼입니다. HackMD에서 콘텐츠를 관리하고 Astro 프로젝트에 표시하기 위해 API를 사용할 수 있습니다.

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-it

pnpm add @hackmd/api markdown-it

yarn add @hackmd/api markdown-it

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로 블로그 만들기

이 예시는 공개적으로 읽을 수 있는 노트의 인덱스와 각 노트마다 정적으로 생성된 페이지를 만듭니다.

노트 목록 표시하기

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>

노트 페이지 생성하기

모든 공개 노트에 대한 정적 페이지를 생성하려면 src/pages/notes/[slug].astro를 만드세요. 노트 목록에서 경로와 노트 ID를 제공한 뒤, getNote()가 해당 페이지의 전체 Markdown 콘텐츠를 가져옵니다:

---
import { client, getNoteSlug, renderMarkdown } from '../../lib/hackmd';

export async function getStaticPaths() {
  const notes = await client.getNoteList();

  return notes
    .filter((note) => note.readPermission === 'guest')
    .map((note) => ({
      params: { slug: getNoteSlug(note) },
      props: { noteId: note.id },
    }));
}

interface Props {
  noteId: string;
}

const { noteId } = Astro.props;
const note = await client.getNote(noteId);
const content = renderMarkdown(note.content);
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{note.title}</title>
  </head>
  <body>
    <main>
      <article>
        <Fragment set:html={content} />
      </article>
    </main>
  </body>
</html>