peekmd 1.0.0 → 1.1.0

package/README.md

@@ -1,86 +1,205 @@
 # peekmd
 
+[![npm version](https://img.shields.io/npm/v/peekmd.svg)](https://www.npmjs.com/package/peekmd)
+[![npm downloads](https://img.shields.io/npm/dm/peekmd.svg)](https://www.npmjs.com/package/peekmd)
+[![GitHub release](https://img.shields.io/github/v/release/HelgeSverre/peekmd)](https://github.com/HelgeSverre/peekmd/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 A CLI tool to preview markdown files with GitHub-style rendering in your browser.
 
 ## Features
 
-- GitHub-flavored markdown rendering
+- GitHub Flavored Markdown (GFM) rendering
 - Syntax highlighting for code blocks
+- GitHub-style alerts (`[!NOTE]`, `[!TIP]`, `[!WARNING]`, `[!IMPORTANT]`, `[!CAUTION]`)
+- Task lists with checkboxes
+- Anchor links on headings
+- File tree sidebar
 - Opens in your default browser automatically
-- Self-contained binary (no runtime dependencies required)
+- Auto-closes when you close the browser tab
 - Cross-platform: macOS, Linux, Windows
 
+## Requirements
+
+**[Bun](https://bun.sh) is required** to run peekmd. Install it with:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
 ## Installation
 
-### From Source
+### Quick Run (no install)
+
+```bash
+# Using bunx (recommended)
+bunx peekmd README.md
+
+# Using npx (requires Bun in PATH)
+npx peekmd README.md
+```
+
+### Global Installation
 
 ```bash
-git clone https://github.com/yourusername/peekmd.git
+# Using bun (recommended)
+bun install -g peekmd
+
+# Using npm (requires Bun in PATH)
+npm install -g peekmd
+```
+
+Then run from anywhere:
+
+```bash
+peekmd README.md
+```
+
+### Manual Installation (from source)
+
+Clone the repository and choose one of the following approaches:
+
+```bash
+git clone https://github.com/HelgeSverre/peekmd.git
 cd peekmd
 bun install
-bun build ./index.ts --compile --outfile peekmd
-chmod +x peekmd
-./peekmd README.md
 ```
 
-### Download Pre-built Binary
+#### Option A: Link for Development
+
+This creates a symlink so you can run `peekmd` from anywhere. Requires Bun to be in your PATH.
 
 ```bash
-# macOS (Apple Silicon)
-curl -L https://github.com/yourusername/peekmd/releases/download/v1.0.0/peekmd-macos-arm64 -o peekmd
-chmod +x peekmd
+bun link
+```
 
-# macOS (Intel)
-curl -L https://github.com/yourusername/peekmd/releases/download/v1.0.0/peekmd-macos-x64 -o peekmd
-chmod +x peekmd
+Now you can run:
 
-# Linux (x64)
-curl -L https://github.com/yourusername/peekmd/releases/download/v1.0.0/peekmd-linux-x64 -o peekmd
-chmod +x peekmd
+```bash
+peekmd /path/to/file.md
+```
 
-# Windows
-curl -L https://github.com/yourusername/peekmd/releases/download/v1.0.0/peekmd-windows-x64.exe -o peekmd.exe
+To unlink later:
+
+```bash
+bun unlink peekmd
+```
+
+#### Option B: Build Standalone Binary
+
+This creates a self-contained executable that works without Bun installed at runtime.
+
+```bash
+bun run compile
+```
+
+This creates a `peekmd` binary in the project directory. Move it to your PATH:
+
+```bash
+# macOS/Linux
+sudo mv peekmd /usr/local/bin/
+
+# Or add to your local bin
+mv peekmd ~/.local/bin/
 ```
 
 ## Usage
 
 ```bash
 # Preview a README file
-./peekmd README.md
+peekmd README.md
 
 # Preview any markdown file
-./peekmd docs/guide.md
+peekmd docs/guide.md
 
 # Preview with full path
-./peekmd /path/to/file.md
+peekmd /path/to/file.md
 ```
 
-## Options
-
-No options required. Simply pass the markdown file path.
-
 ## Controls
 
 - Press `ESC` to close the preview
 - Close the browser tab to exit
 
-## Building
+## What it does
+
+peekmd renders your markdown files with a GitHub-style interface by:
+
+1. **Reading the markdown file** specified in the CLI argument
+2. **Extracting metadata**:
+   - **Description**: Finds the first paragraph after any heading (filters out headings, lists, and code blocks)
+   - **Topics**: Generates placeholder tags based on the repository name (currently hardcoded: "markdown", "preview", "documentation")
+   - **Repository stats**: Placeholder values for stars (0), watchers (1), and forks (0)
+3. **Generating a file tree**: Creates a directory tree view of the current working directory (up to 3 levels deep, max 20 items per level)
+4. **Rendering the markdown**: Converts markdown to HTML with:
+   - GitHub Flavored Markdown (GFM) support
+   - Syntax highlighting for code blocks
+   - GitHub-style alerts (`[!NOTE]`, `[!TIP]`, etc.)
+   - Task lists with checkboxes
+   - Anchor links on headings
+5. **Replacing template placeholders**:
+   - `{{filename}}` - The markdown filename
+   - `{{repoName}}` - The parent directory name
+   - `{{dirPath}}` - The relative directory path
+   - `{{content}}` - The rendered markdown HTML
+   - `{{fileTree}}` - The directory tree structure
+   - `{{description}}` - The extracted description
+   - `{{topics}}` - The generated topic tags
+   - `{{stars}}`, `{{watchers}}`, `{{forks}}` - Repository stats
+6. **Starting a local server** on port 3456 and opening the preview in your default browser
+
+## Development
 
 ```bash
-# Install dependencies
-bun install
+# Run in development mode
+bun run dev
 
-# Build self-contained binary
-bun build ./index.ts --compile --outfile peekmd
+# Format code
+bun run format
 
-# Binary will be ~60MB and include all dependencies
+# Build standalone binary
+bun run compile
 ```
 
-## Requirements
+## Why Bun?
+
+peekmd uses Bun's built-in HTTP server (`Bun.serve()`) for its simplicity and performance. This means:
+
+- Zero configuration HTTP server
+- Native TypeScript execution
+- Fast startup time
+- Small package size (ships TypeScript source, no build step needed)
+
+## Troubleshooting
+
+### "bun: command not found"
+
+Bun is not installed or not in your PATH. Install it:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+Then restart your terminal or run:
+
+```bash
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### "ReferenceError: Bun is not defined"
+
+You're running with Node.js instead of Bun. This can happen if:
+
+- You installed an older version of peekmd
+- The shebang is incorrect
+
+Update to the latest version:
+
+```bash
+bun install -g peekmd@latest
+```
 
-- macOS, Linux, or Windows
-- No external dependencies (self-contained binary)
-- Default browser for preview
+Or if running from source, make sure `cli.ts` has `#!/usr/bin/env bun` as the first line.
 
 ## License
 

package/cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+import { main } from "./index.ts";
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});