Plain Text Tools (ptt)

A small, focused CLI toolkit for Markdown ↔ HTML conversion, built with Node.js and TypeScript.

Philosophy

"The Pragmatic Programmer" emphasizes the Power of Plain Text: plain text is the lowest common denominator, readable by humans and machines alike, and never becomes obsolete. This tool embodies that philosophy by providing simple, composable conversions between two of the most common plain text formats: Markdown and HTML.

Plain text tools are powerful because they:

• Compose well: Chain tools together with pipes
• Never become obsolete: Plain text formats outlive proprietary formats
• Are transparent: You can always inspect and modify the data
• Work everywhere: From scripts to CI/CD pipelines

Installation

npm install
npm run build

For global installation (after building):

npm link

Usage

Markdown to HTML

Convert a Markdown file to HTML:

ptt md2html input.md -o output.html

Read from stdin and write to stdout:

cat README.md | ptt md2html > output.html

Read from stdin and write to a file:

cat input.md | ptt md2html -o output.html

HTML to Markdown

Convert an HTML file to Markdown:

ptt html2md input.html -o output.md

Read from stdin and write to stdout:

curl https://example.com | ptt html2md > output.md

Read from stdin and write to a file:

cat input.html | ptt html2md -o output.md

Examples

Basic Conversion

# Markdown → HTML
ptt md2html README.md -o README.html

# HTML → Markdown
ptt html2md page.html -o page.md

Pipeline Usage

# Convert multiple files
for file in *.md; do
  ptt md2html "$file" -o "${file%.md}.html"
done

# Chain conversions
ptt md2html doc.md | ptt html2md | ptt md2html -o doc-roundtrip.html

Integration with Other Tools

# Convert and serve
ptt md2html README.md | python3 -m http.server 8000

# Extract content from web and convert
curl -s https://example.com/article | ptt html2md > article.md

Features

• ✅ Markdown → HTML: Full Markdown support including GitHub Flavored Markdown
• ✅ HTML → Markdown: Best-effort conversion preserving structure and content
• ✅ stdin/stdout support: Composable with other Unix tools
• ✅ TypeScript: Type-safe implementation
• ✅ Clean architecture: Modular, composable code

Project Structure

src/
  cli.ts          # CLI interface and command definitions
  md2html.ts      # Markdown to HTML conversion
  html2md.ts      # HTML to Markdown conversion
  utils/
    fs.ts         # File system utilities (stdin/stdout handling)

Development

# Build
npm run build

# Watch mode
npm run dev

# Run locally
node dist/cli.js md2html input.md -o output.html

License

MIT