rspress-plugin-graph-view 0.1.1-dev.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Rspress contributors
+
+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

@@ -0,0 +1,161 @@
+# rspress-plugin-graph-view
+
+Interactive graph visualization for [Rspress](https://rspress.dev/) documentation sites. Automatically extracts internal markdown links and renders them as a navigable force-directed graph — like Obsidian's graph view for your docs.
+
+![Version](https://img.shields.io/npm/v/rspress-plugin-graph-view)
+![License](https://img.shields.io/npm/l/rspress-plugin-graph-view)
+
+## Features
+
+- **Automatic link detection** — uses MDAST parsing to extract all markdown link formats (inline, reference, autolinks) while ignoring links inside code blocks
+- **Click to navigate** — click any node to jump to that page
+- **Dark mode** — seamlessly adapts to light and dark themes
+- **Build caching** — incremental rebuilds with mtime-based cache invalidation
+- **Large graph optimization** — automatically disables expensive visual effects for graphs with 80+ nodes
+- **Build profiling** — optional diagnostics to measure graph build performance
+
+## Installation
+
+```bash
+bun add rspress-plugin-graph-view
+# or
+npm install rspress-plugin-graph-view
+# or
+pnpm add rspress-plugin-graph-view
+```
+
+## Usage
+
+Add the plugin to your `rspress.config.ts`:
+
+```ts
+import { defineConfig } from "@rspress/core";
+import graphView from "rspress-plugin-graph-view";
+
+export default defineConfig({
+  // ...your config
+  plugins: [graphView()],
+});
+```
+
+That's it. A floating action button will appear in the bottom-right corner of your docs site. Click it to open the graph view.
+
+### Options
+
+```ts
+graphView({
+  // Open the graph panel by default (default: false)
+  defaultOpen: true,
+
+  // Log build timing diagnostics (default: false)
+  profileBuild: true,
+})
+```
+
+You can also enable profiling temporarily with the `RSPRESS_GRAPH_VIEW_PROFILE=1` environment variable.
+
+### Peer Dependencies
+
+This plugin requires the following peer dependencies, which should already be installed if you're using Rspress:
+
+| Package | Version |
+| --- | --- |
+| `@rspress/core` | `^2.0.7` |
+| `react` | `>=19` |
+| `react-dom` | `>=19` |
+| `react-force-graph-2d` | `^1.29.1` |
+
+## How It Works
+
+1. **Build time**: The plugin collects all route metadata, reads each markdown file, parses the content into an MDAST syntax tree, extracts internal link references, and builds a graph data structure.
+2. **Runtime**: A virtual module (`virtual-graph-data`) injects the graph data into the client. `react-force-graph-2d` renders an interactive force-directed graph with custom canvas drawing.
+3. **Caching**: File mtime + size signatures enable incremental rebuilds — unchanged files skip parsing entirely.
+
+## Architecture
+
+```
+src/
+  index.ts                          ← Plugin entry point (RspressPlugin)
+  types.ts                          ← Core shared types (GraphNode, GraphLink, GraphData)
+  build/
+    index.ts                        ← Public API: buildGraphModule, createGraphBuildCache
+    types.ts                        ← Build-time types (CollectedRoute, GraphBuildOptions)
+    cache.ts                        ← Cache management, pruning, signatures, logging
+    graph-builder.ts                ← Graph construction, route resolution, file aliases
+    link-extractor.ts               ← MDAST parsing, link/title extraction
+  runtime/
+    GraphPanel.tsx                  ← Floating panel with FAB, zoom controls, keyboard a11y
+    GraphView.tsx                   ← Canvas renderer via react-force-graph-2d, error boundary
+    canvas/
+      colors.ts                     ← Light/dark color palettes, theme merging
+    deriveGraphViewData.ts          ← View data derivation (current page + neighbors)
+    virtual-modules.d.ts            ← TypeScript declaration for virtual-graph-data
+```
+
+### Build Pipeline
+
+```
+routeGenerated hook → collect routes → buildGraphModule()
+  ├── pruneStaleDocuments()     — remove deleted routes from cache
+  ├── stat()                    — check mtime + size for each file
+  ├── cache hit?                — reuse parsed data, skip expensive work
+  ├── extractDisplayTitle()     — read frontmatter title or first heading
+  ├── extractMarkdownLinks()    — MDAST parsing → internal link targets
+  ├── createGraphSignature()    — content hash for module-level caching
+  ├── buildGraphData()          — resolve links → build adjacency graph
+  └── serialize → virtual-graph-data module
+```
+
+### Runtime Pipeline
+
+```
+GraphPanel mounts → lazy-loads react-force-graph-2d
+  ├── useLocation() → current route path
+  ├── deriveGraphViewData() → filter graph to current node neighborhood
+  ├── useTheme() → MutationObserver detects dark mode changes
+  ├── canvas rendering → custom nodeCanvasObject with gradients, shadows, hover effects
+  └── onNodeClick → navigate() to target route
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Typecheck
+bun run build
+
+# Run tests
+bun test
+
+# Start docs dev server
+bun run docs:dev
+
+# Benchmark graph build performance
+bun run bench:graph --pages=1000 --links=6 --iterations=5
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Run tests (`bun test`) and typecheck (`bun run build`)
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`)
+6. Push and open a Pull Request
+
+### Commit Convention
+
+This project uses semantic-release for automated versioning. Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` — new feature (triggers minor version bump)
+- `fix:` — bug fix (triggers patch version bump)
+- `docs:` — documentation only
+- `refactor:` — code change that neither fixes a bug nor adds a feature
+- `chore:` — maintenance tasks
+- `ci:` — CI/CD configuration changes
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "rspress-plugin-graph-view",
+  "version": "0.1.1-dev.1",
+  "type": "module",
+  "description": "Interactive graph visualization for Rspress documentation sites — visualize your knowledge base connections like Obsidian",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "rspress",
+    "plugin",
+    "graphview"
+  ],
+  "homepage": "https://github.com/Jacob-Valor/rspress-plugin-graph-view",
+  "bugs": {
+    "url": "https://github.com/Jacob-Valor/rspress-plugin-graph-view/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jacob-Valor/rspress-plugin-graph-view.git"
+  },
+  "license": "MIT",
+  "author": "Jacob-Valor <jacob-programmer@tuta.io> (https://github.com/Jacob-Valor)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./runtime/*": {
+      "import": "./src/runtime/*",
+      "default": "./src/runtime/*"
+    }
+  },
+  "scripts": {
+    "bench:graph": "bun scripts/bench-graph-build.ts",
+    "build": "tsc --declarationMap false",
+    "dev": "tsc -w",
+    "docs:build": "rspress build",
+    "docs:dev": "rspress dev",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun run test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "semantic-release": "^25.0.3",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "@rspress/core": "^2.0.7",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-force-graph-2d": "^1.29.1"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "rspress-plugin-devkit": "^1.0.0"
+  }
+}