PiTH

A visual markdown workspace for people who work with large collections of .md files.

If you've ever maintained a documentation site and found yourself hand-editing a YAML nav file, a sidebars.js, or a custom sidebar config every time you added, renamed, or reorganized a page — this tool is for you.

PiTH gives you a visual, drag-and-drop interface for organizing markdown files into a hierarchy. The hierarchy lives in a tree.yaml that can be anywhere on your filesystem — point PiTH at your existing files instead of moving them. PiTH reads and writes MkDocs nav: configs, custom YAML, and its own format, preserving whatever structure and extra fields your file already has.

Features

Organize

• Visual hierarchy — drag and drop files to reorder and nest them; keyboard shortcuts for fine-grained control
• Unlinked file management — files not in the hierarchy surface automatically; rubber-band, shift-click, and ctrl-click multi-select; multi-drag to hierarchy
• Flatten / restore — flatten the tree to start fresh; restore the saved hierarchy if you change your mind
• Multiple projects — switch between doc sets without losing your place; quick access to the last 5 opened, full searchable list via Open Project

Edit and analyze

• Built-in editor with live preview — split pane with syntax highlighting, rendered preview, and vi mode (:w / :x)
• Readability stats — word count, sentence length, and 5 readability scores per file
• Scan Project — project-wide analysis report with export to HTML/PDF
• Frontmatter templates — define expected keys per project, scan for compliance, batch-update files
• Internal link validation — project-wide broken link scan; per-file panel that re-checks on save
• Full-text search — search across all files with highlighted match context
• Mermaid diagrams — flowcharts, sequence diagrams, and more render live in the preview pane

Import and export

• Point at existing files — create a project by selecting any markdowns directory, or leave it blank and PiTH creates one for you; PiTH works with the files in place rather than copying them
• Use any YAML as your hierarchy — point a project at an existing mkdocs.yml, a custom YAML file, or let PiTH create one; changes are written back preserving the original format and any extra fields
• MkDocs and Docusaurus — import an existing nav config or export when ready to publish
• Add files from anywhere — copy individual .md files into a project from any directory
• HTML/PDF export — whole-collection export to a single document with table of contents and print CSS

Local and private

• Runs entirely on your machine — no cloud, no accounts, no ongoing cost
• Your files stay where they are — PiTH stores only lightweight metadata in ~/.pith/projects/ (hierarchy pointer, template, recent projects). It never copies or moves your markdowns unless you ask it to.
• Available as a PyPI package or standalone executable

Install

Requires Python 3.10+.

pip install pith-md
pith

On Windows and Mac, pith opens a desktop window. On Linux, it starts a server and prints the URL. On WSL, it opens your Windows browser automatically.

Flags

Flag	Effect
--server	Force headless mode on any platform — starts the server and opens a browser tab
--port N	Listen on port N instead of 5000

Linux / remote access

ssh -L 5000:localhost:5000 user@host "/path/to/pith"

Then open http://localhost:5000 in your local browser. Close the terminal to stop PiTH. If you use an SSH config alias (e.g. Host myserver), substitute that for user@host.

To find the pith path on the remote: which pith

Standalone download

No Python required. Download the latest build from the Releases page.

Platform	File
Windows	pith-Windows.zip
Mac	pith-macOS.zip
Linux	pith-Linux.zip

Unzip and run the executable:

• Windows: Double-click pith.exe
• Mac: Right-click → Open the first time to bypass the unsigned app warning
• Linux: Run ./pith from a terminal

Documentation

Full documentation is available at rick-does.github.io/pith.

Run from source

Requires Python 3.12+ and Node.js LTS.

Windows:

git clone git@github.com:rick-does/pith.git
cd pith
start.bat

Mac / Linux / WSL:

git clone git@github.com:rick-does/pith.git
cd pith
./start.sh

Then open http://localhost:8002 in your browser.

Tech stack

• Backend: Python, FastAPI
• Frontend: React, Vite, TypeScript
• Editor: CodeMirror 6 (vi mode via @replit/codemirror-vim)
• Drag and drop: dnd-kit
• Readability: textstat
• YAML: pyyaml (PiTH-native format), ruamel.yaml (round-trip for MkDocs and custom formats)
• Standalone: PyInstaller, pywebview