stormd

A stow-like CLI tool that creates files from code blocks in markdown files or URLs. Perfect for bootstrapping projects, sharing configurations, or distributing code snippets.

Features

• Extract files from markdown - Parse code blocks and create files automatically
• Remote URL support - Fetch markdown from any URL and extract files
• File path comments - Use language-specific comments to specify output paths
• View-only mode - Preview code blocks without creating files using ! prefix
• Safe file creation - Automatically creates directories as needed

Usage

Basic Usage

Process a local markdown file (defaults to stor.md in current directory):

npx stormd
# or
bunx stormd

Process a specific markdown file:

bunx stormd path/to/file.md

Process a remote URL:

bunx stormd https://example.com/setup.md

Markdown Format

Each code block should start with a comment specifying the file path. The tool supports multiple comment styles:

JavaScript/TypeScript Example

```js
// src/app.js
console.log("Hello, world!");
```

Python Example

```python
# scripts/hello.py
print("Hello, world!")
```

Shell Script Example

```bash
# setup.sh
#!/bin/bash
echo "Setting up..."
```

Supported Comment Patterns

• // - JavaScript, TypeScript, C, C++, Rust, Go
• # - Python, Ruby, Bash, YAML
• -- - SQL, Lua, Haskell
• /* */ - CSS, C-style comments
• ; - Lisp, Scheme, Assembly
• % - LaTeX, MATLAB

View-Only Files

Prefix a file path with ! to mark it as view-only. These blocks will be skipped and no file will be created:

```js
// !src/example.js
// This is just for demonstration - won't create a file
console.log("This is view-only!");
```

This is useful for:

• Examples and documentation - Include example code in your markdown without creating files
• Reference snippets - Show helpers or explanations that readers can reference
• Configuration examples - Demonstrate options without modifying actual configs

How It Works

1. Reads markdown content from a local file or remote URL
2. Extracts all code blocks using regex
3. Looks for a file path in the first line (as a comment)
4. Creates the file at the specified path, including any necessary directories
5. Writes the code block content (minus the comment line) to the file

File Creation Behavior

• Local files: Files are created relative to the markdown file's directory
• Remote URLs: Files are created relative to the current working directory
• Absolute paths: Honored regardless of input source
• Missing directories: Created automatically with recursive: true

Example

Create a stor.md file:

# My Project Setup

Here's the main entry point:

```js
// src/index.js
import { hello } from "./lib/hello.js";
hello();
```

And the helper function:

```js
// src/lib/hello.js
export function hello() {
  console.log("Hello from stormd!");
}
```

Configuration file:

```json
// package.json
{
  "name": "my-project",
  "type": "module",
  "version": "1.0.0"
}
```

Here's an example of what NOT to do (view-only):

```js
// !src/bad-example.js
// This won't create a file - just shows what to avoid
console.log("Avoid using var!");
var x = 10;
```

Run the tool:

bunx stormd stor.md

Output:

◐ Processing /path/to/stor.md
ℹ Found 4 code block(s)
ℹ Created /path/to/src/index.js
ℹ Created /path/to/src/lib/hello.js
ℹ Created /path/to/package.json
✔ Created 3 file(s), 1 view-only

Running Tests

bun test

Use Cases

• Project templates - Share entire project structures in a single markdown file
• Documentation with code - Keep docs and code in sync, with view-only examples
• Quick setup scripts - Bootstrap development environments
• Tutorial distribution - Share multi-file tutorials with inline examples
• Configuration sharing - Distribute dotfiles and configs with reference examples

License

MIT