HackMD 与 Astro

HackMD 是一个协作式 Markdown 编辑器和发布平台。你可以使用它的 API 在 HackMD 中管理内容，并将内容显示在 Astro 项目中。

与 Astro 集成

本指南使用官方的 @hackmd/api 客户端获取笔记，并使用 markdown-it 渲染 Markdown 内容。

前置条件

开始之前，你需要准备：

一个 Astro 项目：如果你还没有 Astro 项目，安装指南将帮助你快速开始。
一个 HackMD 账号：你可以免费注册。
一个 HackMD 访问令牌：从你的 HackMD 设置的 API 部分创建令牌。
至少一篇公开可读的笔记：将笔记的读取权限设置为所有人，这样示例才能安全地在你的网站上发布它。

设置凭证

在项目根目录创建一个 .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>