Docsmith

Documentation generator, converter, inspector, and preview server for developer docs.

Docsmith is a terminal-first documentation toolkit for projects that need clean Markdown-to-site publishing without a heavy static-site framework. It can scaffold documentation, scan and validate existing docs, render a static HTML site, convert files between Markdown, HTML, text, JSON, and PDF, search content, extract outlines, and serve a local preview through Flask.

• Static site builder - Render Markdown or HTML docs into a responsive documentation site with navigation and copied assets.
• Format conversion - Convert documentation files to HTML, Markdown, text, JSON metadata, or a lightweight text PDF.
• Schema-style inspection - Summarize files, line counts, word counts, headings, links, and checksums in Rich tables or JSON.
• Validation checks - Detect broken local links, duplicate heading anchors, and Markdown files without headings.
• Fast preview server - Serve generated docs locally with a minimal Flask app.
• Search and outline tools - Locate content across a docs tree and inspect heading structure from the terminal.

Installation

pip install docsmith-cli

Usage

Create a starter documentation folder:

docsmith init docs --title "My Project Docs"

Inspect and validate the documentation tree:

docsmith scan docs
docsmith validate docs

Build a static site and serve it locally:

docsmith build docs --out site
docsmith serve docs --port 8080

Convert a Markdown file:

docsmith convert docs/index.md --to html --out build/index.html
docsmith convert docs/index.md --to pdf

Commands

Configuration

Docsmith works without configuration. The CLI accepts explicit paths and output flags for each command. A typical project layout is:

docs/
  index.md
  guide.md
  reference.md
site/
  index.html
  assets/docsmith.css

Use --json-output with scan or outline when integrating Docsmith into CI or project automation.

License

MIT License. See LICENSE.