astro-smart-links 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 EveSunMaple
+
+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.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+[English](README.md) | [中文](README.zh-CN.md)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# astro-smart-links
+
+An Astro integration that gives every link in your Markdown a smarter style:
+
+- **Internal links** (pages that exist) get a customizable class.
+- **Broken internal links** (pages that do not exist) get a red, Wikipedia-style class and are reported at the end of the build.
+- **External links** get an icon `↗`, `target="_blank"` and `rel="noopener noreferrer"` by default.
+
+No routes file, no second build. The integration validates links against the real build output.
+
+> Migrating from `rehype-smart-links@0.x`? See [Migration](#migration-from-rehype-smart-links).
+
+## Installation
+
+```bash
+# npm
+npm install astro-smart-links
+
+# pnpm
+pnpm add astro-smart-links
+
+# yarn
+yarn add astro-smart-links
+```
+
+## Usage
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import { smartLinks } from "astro-smart-links";
+
+export default defineConfig({
+  integrations: [
+    smartLinks({
+      internalLinkClass: "internal-link",
+      externalLinkClass: "external-link",
+      brokenLinkClass: "broken-link",
+    }),
+  ],
+});
+```
+
+Add the classes to your global CSS:
+
+```css
+.internal-link {
+  color: #2563eb;
+}
+
+/* Wikipedia-style broken link */
+.broken-link {
+  color: #dc2626;
+  text-decoration: underline wavy;
+}
+
+.external-link {
+  color: #7c3aed;
+}
+
+.external-link .external-icon {
+  margin-left: 0.25em;
+  font-size: 0.75em;
+  opacity: 0.8;
+}
+```
+
+## Broken link detection
+
+When the build finishes, the integration scans the generated pages, builds the real route table and:
+
+1. Switches broken internal links from `internal-link` to `broken-link`.
+2. Prints a report to the console.
+3. Optionally writes a `.json`/`.html` report and/or fails the build.
+
+```js
+smartLinks({
+  failOnBroken: true, // exit non-zero on broken links (great for CI)
+  reportFile: ".smart-links-report.json", // or .html
+});
+```
+
+Console output:
+
+```
+[astro-smart-links] Smart links report (2026-01-01T00:00:00.000Z)
+Routes scanned: 42
+Links: 180 internal, 12 external, 2 broken
+
+Broken internal links:
+  /blog/old-post (found in src/content/blog/new-post.md)
+```
+
+Link matching ignores query strings and hashes (`/about?x=1#team` counts as `/about`), resolves relative links against the current page, and handles the Astro `base` sub-path and trailing-slash differences.
+
+## CLI
+
+Check any build directory, even outside Astro:
+
+```bash
+npx astro-smart-links check --dir dist --fail-on-broken
+npx astro-smart-links check --json
+npx astro-smart-links check --all --extensions html pdf zip
+```
+
+| Option | Description |
+| --- | --- |
+| `-d, --dir <path>` | Build directory (default `./dist`) |
+| `-o, --output <path>` | Write the report to a file |
+| `--format <json\|html>` | Report format (default `json`) |
+| `--json` | Print the report to stdout |
+| `-a, --all` | Treat every file type as a valid route |
+| `-e, --extensions <ext...>` | File extensions to include (default `html`) |
+| `--fail-on-broken` | Exit with code 1 when broken links are found |
+| `-q, --quiet` | Only print the summary |
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `internalLinkClass` | `string` | `'internal-link'` | Class for internal links |
+| `externalLinkClass` | `string` | `'external-link'` | Class for external links |
+| `brokenLinkClass` | `string` | `'broken-link'` | Class for broken links |
+| `content` | `{ type: 'text', value: string } \| null` | `{ type: 'text', value: '↗' }` | Content appended to external links |
+| `contentClass` | `string` | `'external-icon'` | Class of the external icon |
+| `target` | `string \| null` | `'_blank'` | `target` attribute for external links |
+| `rel` | `string \| null` | `'noopener noreferrer'` | `rel` attribute for external links |
+| `ignore` | `(string \| RegExp)[]` | `[]` | Hrefs that are never processed (prefix match or RegExp) |
+| `routes` | `string[]` | — | Explicit route list for broken-link detection |
+| `routesFile` | `string` | — | JSON file with a route list |
+| `publicDir` | `string` | — | Directory to scan for routes |
+| `includeFileExtensions` | `string[]` | `['html']` | Extensions treated as routes while scanning |
+| `includeAllFiles` | `boolean` | `false` | Treat every scanned file as a route |
+| `base` | `string` | Astro `base` | Site sub-path |
+| `wrapperTemplate` | `(node, type, meta) => Element` | — | Fully customize the link HTML |
+| `customInternalLinkTransform` | `(node, meta) => void` | — | Custom transform for internal links |
+| `customExternalLinkTransform` | `(node, meta) => void` | — | Custom transform for external links |
+| `customBrokenLinkTransform` | `(node, meta) => void` | — | Custom transform for broken links |
+| `onLink` | `(record) => void` | — | Called for every processed link |
+| `logger` / `logLevel` | `SmartLinksLogger \| false` / `'debug' \| 'info' \| 'warn' \| 'error' \| 'silent'` | `'warn'` | Diagnostics |
+| `failOnBroken` | `boolean` | `false` | Integration option: fail the build on broken links |
+| `reportFile` | `string` | — | Integration option: write a report file |
+| `reportFormat` | `'json' \| 'html'` | `'json'` | Integration option: report format |
+
+## Customization
+
+### Custom HTML structure
+
+`wrapperTemplate` receives the anchor `node`, the link `type` and a `meta` object (`{ href, pathname, className, sourceFile }`), and returns the replacement node:
+
+```js
+smartLinks({
+  wrapperTemplate: (node, type, meta) => {
+    if (type === "external") {
+      node.properties.className = [...(node.properties.className ?? []), "tooltip"];
+      node.properties["data-tip"] = `Opens ${meta.href}`;
+    }
+    return node;
+  },
+});
+```
+
+When `wrapperTemplate` is provided it is responsible for applying classes; `meta.className` contains the configured class for the link type.
+
+### Custom transforms
+
+```js
+smartLinks({
+  customExternalLinkTransform: (node, meta) => {
+    node.properties.target = "_blank";
+    node.properties.rel = "noopener noreferrer";
+    node.properties["data-external"] = "true";
+  },
+});
+```
+
+Custom transforms fully take over the given link type, so set `target`/`rel` yourself when needed.
+
+### Ignoring links
+
+```js
+smartLinks({
+  ignore: ["/draft/", /^\/preview\//],
+});
+```
+
+## Using the rehype plugin directly
+
+The integration is built on an exported rehype plugin, so any rehype-based framework (Next.js, Gatsby, ...) can use it. In that case you provide the routes yourself:
+
+```js
+import { rehypeSmartLinks } from "astro-smart-links";
+
+// unified / Astro markdown config
+rehypePlugins: [
+  [rehypeSmartLinks, { routes: ["/", "/about"] }],
+];
+```
+
+Routes come from `routes`, `routesFile` or `publicDir`. When none is given, every internal link is treated as valid and only styled.
+
+## API
+
+```js
+import {
+  smartLinks, // Astro integration (default export)
+  rehypeSmartLinks, // rehype plugin
+  classifyHref,
+  normalizeRoute,
+  scanRoutes,
+  checkDirectory,
+  buildReport,
+} from "astro-smart-links";
+```
+
+## Migration from rehype-smart-links
+
+`rehype-smart-links@0.x` required a two-phase build (`astro build && rehype-smart-links build && astro build`) and a `.smart-links-routes.json` file. In `astro-smart-links@1.0`:
+
+1. Install `astro-smart-links` and remove `rehype-smart-links`.
+2. Replace the `markdown.rehypePlugins` entry with the `smartLinks()` integration.
+3. Delete the routes file and the `build:with-routes` script.
+4. `wrapperTemplate` now receives `(node, type, meta)` instead of `(node, type, className)`, and returns a replacement node instead of being merged into the original one.
+
+## Development
+
+```bash
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+cd example && pnpm dev
+```
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,239 @@
+[English](README.md) | [中文](README.zh-CN.md)
+
+# astro-smart-links
+
+一个 Astro 集成，让你的 Markdown 链接更智能：
+
+- **内部链接**（页面存在）自动添加可自定义的类名。
+- **断开的内部链接**（页面不存在）添加维基百科风格的红色样式，并在构建结束时输出报告。
+- **外部链接**默认添加 `↗` 图标、`target="_blank"` 和 `rel="noopener noreferrer"`。
+
+无需路由文件，无需二次构建：集成会在构建完成后使用真实的路由表校验链接。
+
+> 从 `rehype-smart-links@0.x` 迁移？见 [迁移指南](#从-rehype-smart-links-迁移)。
+
+## 安装
+
+```bash
+# npm
+npm install astro-smart-links
+
+# pnpm
+pnpm add astro-smart-links
+
+# yarn
+yarn add astro-smart-links
+```
+
+## 使用
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import { smartLinks } from "astro-smart-links";
+
+export default defineConfig({
+  integrations: [
+    smartLinks({
+      internalLinkClass: "internal-link",
+      externalLinkClass: "external-link",
+      brokenLinkClass: "broken-link",
+    }),
+  ],
+});
+```
+
+在全局 CSS 中添加样式：
+
+```css
+.internal-link {
+  color: #2563eb;
+}
+
+/* 维基百科风格的红链 */
+.broken-link {
+  color: #dc2626;
+  text-decoration: underline wavy;
+}
+
+.external-link {
+  color: #7c3aed;
+}
+
+.external-link .external-icon {
+  margin-left: 0.25em;
+  font-size: 0.75em;
+  opacity: 0.8;
+}
+```
+
+## 断链检测
+
+构建完成后，集成会扫描生成的页面、得到真实路由表，然后：
+
+1. 将断链从 `internal-link` 切换为 `broken-link`。
+2. 在控制台输出报告。
+3. 可选：写入 `.json`/`.html` 报告文件，和/或让构建失败。
+
+```js
+smartLinks({
+  failOnBroken: true, // 发现断链时退出码非 0，适合 CI
+  reportFile: ".smart-links-report.json", // 也可以是 .html
+});
+```
+
+控制台输出示例：
+
+```
+[astro-smart-links] Smart links report (2026-01-01T00:00:00.000Z)
+Routes scanned: 42
+Links: 180 internal, 12 external, 2 broken
+
+Broken internal links:
+  /blog/old-post (found in src/content/blog/new-post.md)
+```
+
+链接匹配会自动忽略查询参数与哈希（`/about?x=1#team` 视为 `/about`），按当前页面解析相对链接，并处理 Astro `base` 子路径与结尾斜杠差异。
+
+## CLI
+
+可以检查任何构建目录，不限于 Astro 项目：
+
+```bash
+npx astro-smart-links check --dir dist --fail-on-broken
+npx astro-smart-links check --json
+npx astro-smart-links check --all --extensions html pdf zip
+```
+
+| 选项 | 描述 |
+| --- | --- |
+| `-d, --dir <path>` | 构建目录（默认 `./dist`） |
+| `-o, --output <path>` | 将报告写入文件 |
+| `--format <json\|html>` | 报告格式（默认 `json`） |
+| `--json` | 以 JSON 输出到 stdout |
+| `-a, --all` | 将所有文件类型视为有效路由 |
+| `-e, --extensions <ext...>` | 要包含的文件扩展名（默认 `html`） |
+| `--fail-on-broken` | 发现断链时以退出码 1 结束 |
+| `-q, --quiet` | 只输出摘要 |
+
+## 配置选项
+
+| 选项 | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| `internalLinkClass` | `string` | `'internal-link'` | 内部链接的类名 |
+| `externalLinkClass` | `string` | `'external-link'` | 外部链接的类名 |
+| `brokenLinkClass` | `string` | `'broken-link'` | 断链的类名 |
+| `content` | `{ type: 'text', value: string } \| null` | `{ type: 'text', value: '↗' }` | 外部链接追加的内容 |
+| `contentClass` | `string` | `'external-icon'` | 外部链接图标的类名 |
+| `target` | `string \| null` | `'_blank'` | 外部链接的 `target` |
+| `rel` | `string \| null` | `'noopener noreferrer'` | 外部链接的 `rel` |
+| `ignore` | `(string \| RegExp)[]` | `[]` | 不处理的链接（前缀匹配或正则） |
+| `routes` | `string[]` | — | 显式路由列表 |
+| `routesFile` | `string` | — | 包含路由列表的 JSON 文件 |
+| `publicDir` | `string` | — | 扫描路由的目录 |
+| `includeFileExtensions` | `string[]` | `['html']` | 扫描时视为路由的扩展名 |
+| `includeAllFiles` | `boolean` | `false` | 将所有扫描到的文件视为路由 |
+| `base` | `string` | Astro `base` | 站点子路径 |
+| `wrapperTemplate` | `(node, type, meta) => Element` | — | 完全自定义链接的 HTML |
+| `customInternalLinkTransform` | `(node, meta) => void` | — | 内部链接自定义转换 |
+| `customExternalLinkTransform` | `(node, meta) => void` | — | 外部链接自定义转换 |
+| `customBrokenLinkTransform` | `(node, meta) => void` | — | 断链自定义转换 |
+| `onLink` | `(record) => void` | — | 每个已处理链接的回调 |
+| `logger` / `logLevel` | `SmartLinksLogger \| false` / `'debug' \| 'info' \| 'warn' \| 'error' \| 'silent'` | `'warn'` | 日志 |
+| `failOnBroken` | `boolean` | `false` | 集成选项：发现断链时让构建失败 |
+| `reportFile` | `string` | — | 集成选项：写入报告文件 |
+| `reportFormat` | `'json' \| 'html'` | `'json'` | 集成选项：报告格式 |
+
+## 自定义
+
+### 自定义 HTML 结构
+
+`wrapperTemplate` 接收锚点 `node`、链接 `type` 和 `meta`（`{ href, pathname, className, sourceFile }`），返回替换后的节点：
+
+```js
+smartLinks({
+  wrapperTemplate: (node, type, meta) => {
+    if (type === "external") {
+      node.properties.className = [...(node.properties.className ?? []), "tooltip"];
+      node.properties["data-tip"] = `打开 ${meta.href}`;
+    }
+    return node;
+  },
+});
+```
+
+使用 `wrapperTemplate` 时由它负责添加类名；`meta.className` 中包含当前类型配置的类名。
+
+### 自定义转换
+
+```js
+smartLinks({
+  customExternalLinkTransform: (node, meta) => {
+    node.properties.target = "_blank";
+    node.properties.rel = "noopener noreferrer";
+    node.properties["data-external"] = "true";
+  },
+});
+```
+
+自定义转换会完全接管该类型的链接，需要自行设置 `target`/`rel`。
+
+### 忽略链接
+
+```js
+smartLinks({
+  ignore: ["/draft/", /^\/preview\//],
+});
+```
+
+## 直接使用 rehype 插件
+
+集成基于一个导出的 rehype 插件实现，因此任何使用 rehype 的框架（Next.js、Gatsby 等）都可以使用。此时需要自行提供路由：
+
+```js
+import { rehypeSmartLinks } from "astro-smart-links";
+
+rehypePlugins: [
+  [rehypeSmartLinks, { routes: ["/", "/about"] }],
+];
+```
+
+路由来源三选一：`routes`、`routesFile` 或 `publicDir`。都不提供时，所有内部链接都会被视为有效链接，只做样式标记。
+
+## API
+
+```js
+import {
+  smartLinks, // Astro 集成（默认导出）
+  rehypeSmartLinks, // rehype 插件
+  classifyHref,
+  normalizeRoute,
+  scanRoutes,
+  checkDirectory,
+  buildReport,
+} from "astro-smart-links";
+```
+
+## 从 rehype-smart-links 迁移
+
+`rehype-smart-links@0.x` 需要二次构建（`astro build && rehype-smart-links build && astro build`）和 `.smart-links-routes.json` 文件。升级到 `astro-smart-links@1.0`：
+
+1. 安装 `astro-smart-links`，移除 `rehype-smart-links`。
+2. 把 `markdown.rehypePlugins` 配置替换为 `smartLinks()` 集成。
+3. 删除路由文件与 `build:with-routes` 脚本。
+4. `wrapperTemplate` 签名变为 `(node, type, meta)`，并改为返回替换节点（不再合并到原节点）。
+
+## 开发
+
+```bash
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+cd example && pnpm dev
+```
+
+## 许可证
+
+[MIT](LICENSE)