next-staticblog 0.2.0-beta.2 → 0.2.0-beta.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 yd-tw
+Copyright (c) 2025-2026 yd-tw
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README-zh.md

@@ -0,0 +1,298 @@
+# next-posts
+
+> 載入文章並將 YAML 解析到 Next.js 中！
+
+一個輕量、零依賴的 TypeScript 函式庫，用於在 Next.js 中建立靜態部落格等文章頁面。它會解析包含 YAML frontmatter 的 Markdown 檔案，並提供簡潔的工具函式，方便搭配 SSG（Static Site Generation）使用。
+
+---
+
+## 功能特色
+
+- 零執行期依賴 —— 僅使用 Node.js 內建模組
+- 完整 TypeScript 支援（支援泛型 metadata）
+- 支援任意目錄結構
+- 同時支援 `slug` 與 `slug.md` 輸入格式
+- 相容 Next.js App Router 與 Pages Router
+
+---
+
+## 安裝
+
+使用 npm 或你喜歡的套件管理工具。
+
+```bash
+npm install next-posts
+```
+
+---
+
+## 快速開始
+
+在專案根目錄建立 `posts/` 資料夾，並放入 Markdown 檔案：
+
+```
+my-next-app/
+└── posts/
+    ├── hello-world.md
+    └── getting-started.md
+```
+
+每個檔案應包含 YAML frontmatter 區塊與文章內容：
+
+```markdown
+---
+title: Hello World
+date: 2024-01-01
+tags:
+  - blog
+  - intro
+---
+
+Welcome to my blog!
+```
+
+接著在 Next.js 中使用：
+
+```ts
+import { getAllPosts, getPostBySlug, getAllPostParams } from "next-posts";
+
+interface PostMeta {
+  title: string;
+  date: string;
+  tags?: string[];
+}
+
+// 取得所有文章
+const posts = getAllPosts<PostMeta>();
+
+// 取得單篇文章
+const post = getPostBySlug<PostMeta>("hello-world");
+
+// 產生靜態路徑（Next.js）
+const paths = getAllPostParams();
+```
+
+---
+
+## API
+
+### `getAllPosts<T>(directory?)`
+
+回傳指定目錄中的所有文章，包含解析後的 frontmatter 與內容。
+
+```ts
+const posts = getAllPosts<PostMeta>();
+// [
+//   { slug: 'hello-world', metadata: { title: '...' }, content: '...' },
+//   ...
+// ]
+```
+
+| 參數        | 型別     | 預設值     | 說明                          |
+| ----------- | -------- | ---------- | ----------------------------- |
+| `directory` | `string` | `"posts/"` | 相對於 `process.cwd()` 的路徑 |
+
+**回傳型別：**
+`Array<{ slug: string; metadata: T; content: string }>`
+
+---
+
+### `getPostBySlug<T>(slug, directory?)`
+
+依據 slug 取得單篇文章。支援帶或不帶 `.md` 副檔名。
+
+```ts
+const post = getPostBySlug<PostMeta>("hello-world");
+// {
+//   slug: 'hello-world',
+//   metadata: { title: 'Hello World', ... },
+//   content: '...'
+// }
+```
+
+| 參數        | 型別     | 預設值     | 說明                          |
+| ----------- | -------- | ---------- | ----------------------------- |
+| `slug`      | `string` | —          | 檔名（可含或不含 `.md`）      |
+| `directory` | `string` | `"posts/"` | 相對於 `process.cwd()` 的路徑 |
+
+**回傳型別：**
+`{ slug: string; metadata: T; content: string }`
+
+---
+
+### `getAllPostSlugs(directory?)`
+
+回傳指定目錄中的原始檔名（包含 `.md` 副檔名）。
+
+```ts
+const slugs = getAllPostSlugs();
+// ['hello-world.md', 'getting-started.md']
+```
+
+| 參數        | 型別     | 預設值     | 說明                          |
+| ----------- | -------- | ---------- | ----------------------------- |
+| `directory` | `string` | `"posts/"` | 相對於 `process.cwd()` 的路徑 |
+
+**回傳型別：**
+`string[]`
+
+---
+
+### `getAllPostParams(directory?)`
+
+回傳適用於 Next.js `generateStaticParams` 或 `getStaticPaths` 的 slug 參數物件，會自動移除 `.md` 副檔名。
+
+```ts
+const params = getAllPostParams();
+// [{ slug: 'hello-world' }, { slug: 'getting-started' }]
+```
+
+| 參數        | 型別     | 預設值     | 說明                          |
+| ----------- | -------- | ---------- | ----------------------------- |
+| `directory` | `string` | `"posts/"` | 相對於 `process.cwd()` 的路徑 |
+
+**回傳型別：**
+`Array<{ slug: string }>`
+
+---
+
+### `parseFrontmatter(input)`
+
+解析原始 Markdown 字串並提取 YAML frontmatter。適用於非從檔案系統讀取的 Markdown，或需要較底層控制時使用。
+
+```ts
+import { parseFrontmatter } from "next-posts";
+
+const raw = `---
+title: Hello World
+date: 2024-01-01
+tags:
+  - blog
+---
+
+Welcome to my blog!`;
+
+const { data, content } = parseFrontmatter(raw);
+```
+
+- `data`：解析後的 YAML frontmatter 物件，若無有效 frontmatter 則為 `{}`。
+- `content`：移除 frontmatter 後的 Markdown 內容。
+
+| 參數    | 型別     | 說明                             |
+| ------- | -------- | -------------------------------- |
+| `input` | `string` | 含有 frontmatter 的原始 Markdown |
+
+**回傳型別：**
+`{ data: Record<string, unknown>; content: string }`
+
+---
+
+## 搭配 Next.js 使用
+
+### App Router
+
+```ts
+// app/blog/[slug]/page.tsx
+import { getAllPostParams, getPostBySlug } from 'next-posts';
+
+interface PostMeta {
+  title: string;
+  date: string;
+}
+
+export function generateStaticParams() {
+  return getAllPostParams();
+}
+
+export default function BlogPost({ params }: { params: { slug: string } }) {
+  const { metadata, content } = getPostBySlug<PostMeta>(params.slug);
+
+  return (
+    <article>
+      <h1>{metadata.title}</h1>
+      <p>{metadata.date}</p>
+      <div dangerouslySetInnerHTML={{ __html: content }} />
+    </article>
+  );
+}
+```
+
+---
+
+### Pages Router
+
+```ts
+// pages/blog/[slug].tsx
+import { GetStaticPaths, GetStaticProps } from "next";
+import { getAllPostParams, getPostBySlug } from "next-posts";
+
+interface PostMeta {
+  title: string;
+  date: string;
+}
+
+export const getStaticPaths: GetStaticPaths = () => ({
+  paths: getAllPostParams().map(({ slug }) => ({ params: { slug } })),
+  fallback: false,
+});
+
+export const getStaticProps: GetStaticProps = ({ params }) => {
+  const post = getPostBySlug<PostMeta>(params!.slug as string);
+  return { props: { post } };
+};
+```
+
+---
+
+## 自訂文章目錄
+
+所有函式皆支援傳入自訂目錄：
+
+```ts
+const posts = getAllPosts("content/articles/");
+const post = getPostBySlug("my-article", "content/articles/");
+```
+
+---
+
+## 從 v0.x 版本遷移
+
+遷移過程很容易，因為大部分的 API 都保持兼容。
+
+1. 變更套件名稱：
+
+`next-posts` 過去稱為 `next-staticblog` ，你可以直接替換套件名稱並指向最新版本。舊的套件將棄用並不再進行維護。
+
+2. 明確的型別：
+
+在 `v0.x` 版本中使用 `any` 來定義 `metadata`，在 `v1.x` 版本中改為使用 `unknown` 來提升安全性。
+請閱讀文檔瞭解如何傳入泛型，擁有安全的型別。
+
+除此之外套件移除了 `gray-matter` 並改用 `@std/yaml` 進行解析。雖然變更通過了所有的測試，但仍然可能在部分非標準用法上有細微差異。
+
+---
+
+## 貢獻
+
+你可以透過回報問題或提交新功能完善這個套件！
+
+```bash
+# 安裝依賴
+npm install
+
+# 建置
+npm run build
+
+# 執行測試
+npm test
+
+# 格式化程式碼
+npm run format
+```
+
+---
+
+## 授權
+
+MIT © yd-tw
+[https://github.com/yd-tw/next-posts](https://github.com/yd-tw/next-posts)

package/README.md

@@ -1,3 +1,260 @@
-# next-staticblog
-
-Quickly configure the markdown component in the Next.js project and create a blog page!
+# next-staticblog
+
+> Quickly configure the markdown component in a Next.js project and create a blog page!
+
+A lightweight, zero-runtime-dependency TypeScript library for building static blogs in Next.js. It parses markdown files with YAML frontmatter and provides simple utilities to retrieve posts for use with static site generation (SSG).
+
+## Features
+
+- Zero runtime dependencies — uses Node.js built-ins only
+- Full TypeScript support with generic metadata types
+- Works with any directory structure
+- Handles both `slug` and `slug.md` inputs transparently
+- Compatible with Next.js App Router and Pages Router
+
+## Installation
+
+```bash
+npm install next-staticblog
+```
+
+```bash
+pnpm add next-staticblog
+```
+
+```bash
+yarn add next-staticblog
+```
+
+## Quick Start
+
+Place your markdown files in a `posts/` directory at the project root:
+
+```
+my-next-app/
+└── posts/
+    ├── hello-world.md
+    └── getting-started.md
+```
+
+Each file should contain a YAML frontmatter block followed by the post content:
+
+```markdown
+---
+title: Hello World
+date: 2024-01-01
+tags:
+  - blog
+  - intro
+---
+
+Welcome to my blog!
+```
+
+Then use the library in your Next.js pages:
+
+```typescript
+import { getAllPosts, getPostBySlug, getAllPostParams } from "next-staticblog";
+
+interface PostMeta {
+  title: string;
+  date: string;
+  tags?: string[];
+}
+
+// Get all posts
+const posts = getAllPosts<PostMeta>();
+
+// Get a single post
+const post = getPostBySlug<PostMeta>("hello-world");
+
+// Generate static paths (Next.js)
+const paths = getAllPostParams();
+```
+
+## API
+
+### `getAllPosts<T>(directory?)`
+
+Returns all posts from the specified directory, each with parsed frontmatter and content.
+
+```typescript
+const posts = getAllPosts<PostMeta>();
+// [{ slug: 'hello-world', metadata: { title: '...' }, content: '...' }, ...]
+```
+
+| Parameter   | Type     | Default    | Description                      |
+| ----------- | -------- | ---------- | -------------------------------- |
+| `directory` | `string` | `"posts/"` | Path relative to `process.cwd()` |
+
+**Returns:** `Array<{ slug: string; metadata: T; content: string }>`
+
+---
+
+### `getPostBySlug<T>(slug, directory?)`
+
+Returns a single post by slug. Accepts slugs with or without the `.md` extension.
+
+```typescript
+const post = getPostBySlug<PostMeta>("hello-world");
+// { slug: 'hello-world', metadata: { title: 'Hello World', ... }, content: '...' }
+```
+
+| Parameter   | Type     | Default    | Description                      |
+| ----------- | -------- | ---------- | -------------------------------- |
+| `slug`      | `string` | —          | Filename with or without `.md`   |
+| `directory` | `string` | `"posts/"` | Path relative to `process.cwd()` |
+
+**Returns:** `{ slug: string; metadata: T; content: string }`
+
+---
+
+### `getAllPostSlugs(directory?)`
+
+Returns the raw filenames (including `.md` extension) from the specified directory.
+
+```typescript
+const slugs = getAllPostSlugs();
+// ['hello-world.md', 'getting-started.md']
+```
+
+| Parameter   | Type     | Default    | Description                      |
+| ----------- | -------- | ---------- | -------------------------------- |
+| `directory` | `string` | `"posts/"` | Path relative to `process.cwd()` |
+
+**Returns:** `string[]`
+
+---
+
+### `getAllPostParams(directory?)`
+
+Returns slug parameter objects suitable for use with Next.js `generateStaticParams` or `getStaticPaths`. The `.md` extension is stripped automatically.
+
+```typescript
+const params = getAllPostParams();
+// [{ slug: 'hello-world' }, { slug: 'getting-started' }]
+```
+
+| Parameter   | Type     | Default    | Description                      |
+| ----------- | -------- | ---------- | -------------------------------- |
+| `directory` | `string` | `"posts/"` | Path relative to `process.cwd()` |
+
+**Returns:** `Array<{ slug: string }>`
+
+---
+
+### `parseFrontmatter(input)`
+
+Parses a raw markdown string and extracts YAML frontmatter metadata. Useful when you have markdown content not loaded from the filesystem, or when you need lower-level parsing control.
+
+```typescript
+import { parseFrontmatter } from "next-staticblog";
+
+const raw = `---
+title: Hello World
+date: 2024-01-01
+tags:
+  - blog
+---
+
+Welcome to my blog!`;
+
+const { data, content } = parseFrontmatter(raw);
+// data:    { title: 'Hello World', date: '2024-01-01', tags: ['blog'] }
+// content: '\nWelcome to my blog!'
+```
+
+| Parameter | Type     | Description                          |
+| --------- | -------- | ------------------------------------ |
+| `input`   | `string` | Raw markdown string with frontmatter |
+
+**Returns:** `{ data: Record<string, unknown>; content: string }`
+
+- `data` — parsed YAML frontmatter as a plain object. Returns `{}` if no valid frontmatter is found.
+- `content` — the markdown body after the frontmatter block.
+
+---
+
+## Usage with Next.js
+
+### App Router (Next.js 13+)
+
+```typescript
+// app/blog/[slug]/page.tsx
+import { getAllPostParams, getPostBySlug } from 'next-staticblog';
+
+interface PostMeta {
+  title: string;
+  date: string;
+}
+
+export function generateStaticParams() {
+  return getAllPostParams();
+}
+
+export default function BlogPost({ params }: { params: { slug: string } }) {
+  const { metadata, content } = getPostBySlug<PostMeta>(params.slug);
+
+  return (
+    <article>
+      <h1>{metadata.title}</h1>
+      <p>{metadata.date}</p>
+      {/* render content with your preferred markdown renderer */}
+      <div dangerouslySetInnerHTML={{ __html: content }} />
+    </article>
+  );
+}
+```
+
+### Pages Router
+
+```typescript
+// pages/blog/[slug].tsx
+import { GetStaticPaths, GetStaticProps } from "next";
+import { getAllPostParams, getPostBySlug } from "next-staticblog";
+
+interface PostMeta {
+  title: string;
+  date: string;
+}
+
+export const getStaticPaths: GetStaticPaths = () => ({
+  paths: getAllPostParams().map(({ slug }) => ({ params: { slug } })),
+  fallback: false,
+});
+
+export const getStaticProps: GetStaticProps = ({ params }) => {
+  const post = getPostBySlug<PostMeta>(params!.slug as string);
+  return { props: { post } };
+};
+```
+
+### Custom Post Directory
+
+All functions accept an optional `directory` parameter:
+
+```typescript
+// Use a custom directory
+const posts = getAllPosts("content/articles/");
+const post = getPostBySlug("my-article", "content/articles/");
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Format code
+npm run format
+```
+
+## License
+
+MIT © [twyd](https://github.com/yd-tw/next-staticblog)

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 export declare function getAllPostSlugs(directory?: string): string[];
-export declare function getAllPosts(directory?: string): {
+export declare function getAllPosts<T extends Record<string, unknown> = Record<string, unknown>>(directory?: string): {
     slug: string;
-    metadata: Record<string, unknown>;
+    metadata: T;
     content: string;
 }[];
 export declare function getAllPostParams(directory?: string): {
     slug: string;
 }[];
-export declare function getPostBySlug(slug: string, directory?: string): {
+export declare function getPostBySlug<T extends Record<string, unknown> = Record<string, unknown>>(slug: string, directory?: string): {
     slug: string;
-    metadata: Record<string, unknown>;
+    metadata: T;
     content: string;
 };