next-posts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-zh.md

@@ -0,0 +1,334 @@
+# 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();
+```
+
+### 模板
+
+你也可以從模板開始：
+
+- [next-profile-template](https://github.com/yd-tw/next-profile-template)
+- [kuang-ti-web](https://github.com/yd-tw/kuang-ti-web)
+
+---
+
+## 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
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { getAllPostParams, getPostBySlug } from "next-posts";
+
+interface PostMeta {
+  title: string;
+  date: string;
+}
+
+export function generateStaticParams() {
+  return getAllPostParams();
+}
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const { metadata, content } = getPostBySlug<PostMeta>(slug);
+
+  return (
+    <article>
+      <h1>{metadata.title}</h1>
+      <p>{metadata.date}</p>
+      {/* 推薦使用 ReactMarkdown，但你可以使用任何喜愛的 */}
+      <ReactMarkdown>{post.content}</ReactMarkdown>
+    </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` 進行解析。雖然變更通過了所有的測試，但仍然可能在部分非標準用法上有細微差異。
+
+---
+
+## 常見問題
+
+### no such file or directory
+
+我們推薦你使用 SSG 建置，因為這樣才能確保最高效率。因此若你在動態路由中使用 `next-posts` 將有可能導致錯誤。
+幸運的是通常你只需要使用 `getAllPostParams()` 並結合 `generateStaticParams()` 就能使用 `SSG`。
+
+```ts
+Error: ENOENT: no such file or directory, scandir '/var/task/posts/news/zh'
+```
+
+但若你堅持使用動態路由，則需要在 next.config.ts 添加設置以確保文章能夠被包含。
+
+```ts
+// next.config.ts
+outputFileTracingIncludes: {
+  "/**": ["./posts/**/*.{md,mdx}"],
+},
+```
+
+---
+
+## 貢獻
+
+你可以透過回報問題或提交新功能完善這個套件！
+
+```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

@@ -0,0 +1,337 @@
+# next-posts
+
+> Load posts and parse YAML into Next.js!
+
+A lightweight, zero-dependency TypeScript library for building static blog posts and content pages in Next.js. It parses Markdown files with YAML frontmatter and provides simple utility functions designed for use with SSG (Static Site Generation).
+
+[中文](/README-zh.md)
+
+---
+
+## Features
+
+- Zero runtime dependencies — only uses built-in Node.js modules
+- Full TypeScript support (generic metadata support)
+- Supports arbitrary directory structures
+- Accepts both `slug` and `slug.md` formats
+- Compatible with Next.js App Router and Pages Router
+
+---
+
+## Installation
+
+Install using npm or your preferred package manager:
+
+```bash
+npm install next-posts
+```
+
+---
+
+## Quick Start
+
+Create a `posts/` directory in your project root and add Markdown files:
+
+```
+my-next-app/
+└── posts/
+    ├── hello-world.md
+    └── getting-started.md
+```
+
+Each file should contain a YAML frontmatter block and content:
+
+```markdown
+---
+title: Hello World
+date: 2024-01-01
+tags:
+  - blog
+  - intro
+---
+
+Welcome to my blog!
+```
+
+Then use it in your Next.js project:
+
+```ts
+import { getAllPosts, getPostBySlug, getAllPostParams } from "next-posts";
+
+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();
+```
+
+### Template
+
+You can also start with a template：
+
+- [next-profile-template](https://github.com/yd-tw/next-profile-template)
+- [kuang-ti-web](https://github.com/yd-tw/kuang-ti-web)
+
+---
+
+## API
+
+### `getAllPosts<T>(directory?)`
+
+Returns all posts from the specified directory, including parsed frontmatter and content.
+
+```ts
+const posts = getAllPosts<PostMeta>();
+// [
+//   { slug: 'hello-world', metadata: { title: '...' }, content: '...' },
+//   ...
+// ]
+```
+
+| Parameter   | Type     | Default    | Description                      |
+| ----------- | -------- | ---------- | -------------------------------- |
+| `directory` | `string` | `"posts/"` | Path relative to `process.cwd()` |
+
+**Return type:**
+`Array<{ slug: string; metadata: T; content: string }>`
+
+---
+
+### `getPostBySlug<T>(slug, directory?)`
+
+Returns a single post by slug. Supports both with and without the `.md` extension.
+
+```ts
+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()` |
+
+**Return type:**
+`{ slug: string; metadata: T; content: string }`
+
+---
+
+### `getAllPostSlugs(directory?)`
+
+Returns all raw filenames (including the `.md` extension) from the specified directory.
+
+```ts
+const slugs = getAllPostSlugs();
+// ['hello-world.md', 'getting-started.md']
+```
+
+| Parameter   | Type     | Default    | Description                      |
+| ----------- | -------- | ---------- | -------------------------------- |
+| `directory` | `string` | `"posts/"` | Path relative to `process.cwd()` |
+
+**Return type:**
+`string[]`
+
+---
+
+### `getAllPostParams(directory?)`
+
+Returns slug parameter objects suitable for Next.js `generateStaticParams` or `getStaticPaths`. Automatically removes the `.md` extension.
+
+```ts
+const params = getAllPostParams();
+// [{ slug: 'hello-world' }, { slug: 'getting-started' }]
+```
+
+| Parameter   | Type     | Default    | Description                      |
+| ----------- | -------- | ---------- | -------------------------------- |
+| `directory` | `string` | `"posts/"` | Path relative to `process.cwd()` |
+
+**Return type:**
+`Array<{ slug: string }>`
+
+---
+
+### `parseFrontmatter(input)`
+
+Parses a raw Markdown string and extracts YAML frontmatter. Useful when Markdown is not loaded from the filesystem or when lower-level control is needed.
+
+```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`: Parsed YAML frontmatter object. Returns `{}` if no valid frontmatter exists.
+- `content`: Markdown content with the frontmatter removed.
+
+| Parameter | Type     | Description                                |
+| --------- | -------- | ------------------------------------------ |
+| `input`   | `string` | Raw Markdown string containing frontmatter |
+
+**Return type:**
+`{ data: Record<string, unknown>; content: string }`
+
+---
+
+## Using with Next.js
+
+### App Router
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { getAllPostParams, getPostBySlug } from "next-posts";
+
+interface PostMeta {
+  title: string;
+  date: string;
+}
+
+export function generateStaticParams() {
+  return getAllPostParams();
+}
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const { metadata, content } = getPostBySlug<PostMeta>(slug);
+
+  return (
+    <article>
+      <h1>{metadata.title}</h1>
+      <p>{metadata.date}</p>
+      {/* ReactMarkdown is recommended, but you can use any renderer you prefer */}
+      <ReactMarkdown>{content}</ReactMarkdown>
+    </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 } };
+};
+```
+
+---
+
+## Custom Post Directory
+
+All functions accept a custom directory:
+
+```ts
+const posts = getAllPosts("content/articles/");
+const post = getPostBySlug("my-article", "content/articles/");
+```
+
+---
+
+## Migrating from v0.x
+
+Migration is straightforward since most APIs remain compatible.
+
+1. Package rename:
+
+`next-posts` was previously called `next-staticblog`. Simply replace the package name and install the latest version. The old package is deprecated and no longer maintained.
+
+2. Explicit typing:
+
+In `v0.x`, `metadata` was typed as `any`.
+In `v1.x`, it is typed as `unknown` to improve type safety.
+Refer to the documentation on how to pass generics for safe typing.
+
+Additionally, the package removed `gray-matter` and now uses `@std/yaml` for parsing. While all tests pass, there may be minor differences in some non-standard use cases.
+
+---
+
+## FAQ
+
+### no such file or directory
+
+SSG is strongly recommended for maximum efficiency. Using `next-posts` inside dynamic routes may cause errors.
+
+Typically, you only need to combine `getAllPostParams()` with `generateStaticParams()` to enable SSG.
+
+```ts
+Error: ENOENT: no such file or directory, scandir '/var/task/posts/news/zh'
+```
+
+If you insist on using dynamic routes, add the following configuration to `next.config.ts` to ensure Markdown files are included:
+
+```ts
+// next.config.ts
+outputFileTracingIncludes: {
+  "/**": ["./posts/**/*.{md,mdx}"],
+},
+```
+
+---
+
+## Contributing
+
+You can improve this package by reporting issues or submitting new features!
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Format code
+npm run format
+```
+
+---
+
+## License
+
+MIT © yd-tw
+[https://github.com/yd-tw/next-posts](https://github.com/yd-tw/next-posts)

package/dist/index.d.ts

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