OpenHands Markdown Document Tool
A comprehensive tool for structural editing and formatting of markdown documents, designed for use with OpenHands AI agents.
Features
This tool provides AI agents with powerful markdown document manipulation capabilities:
Document Structure
- Overview - Display hierarchical document structure with sections, line numbers, and nesting
- Validate - Check section numbering consistency and table of contents accuracy
- Renumber - Automatically fix section numbering sequentially
Table of Contents
- Generate/Update TOC - Create or refresh table of contents with configurable depth
- Remove TOC - Clean removal of table of contents section
Section Operations
- Move - Relocate sections (with children) to new positions
- Insert - Add new sections at specific locations
- Delete - Remove sections and their subsections
- Promote - Increase heading level (### → ##)
- Demote - Decrease heading level (## → ###)
Formatting
- Rewrap - Normalize paragraph line lengths with smart wrapping
- Lint - Detect markdown formatting issues
- Fix - Auto-fix common markdown problems
- Cleanup - Comprehensive cleanup (rewrap + fix + renumber + update TOC)
Installation
The core library (markdown parsing, numbering, TOC, formatting) has no dependency on the OpenHands SDK:
pip install oh-markdown-tool # or: uv pip install oh-markdown-tool
To use it as an OpenHands agent tool, install the openhands extra. It pulls in
openhands-sdk, which requires Python 3.12+:
pip install "oh-markdown-tool[openhands]"
Usage as an OpenHands agent tool
The tool lives in oh_markdown_tool.tool; importing that module registers it under the
name markdown_document.
from openhands.sdk import Agent
from oh_markdown_tool.tool import MarkdownDocumentTool
# Create an agent with the markdown tool
agent = Agent(
tools=[MarkdownDocumentTool],
# ... other configuration
)
# The agent can now use commands like:
# - "Show me the overview of doc/design.md"
# - "Renumber the sections in README.md"
# - "Update the table of contents in design.md"
# - "Move section 4.3 to after section 2"
On a remote agent-server, reference the tool by its module qualname so the server imports and registers it on conversation creation:
"tools": [{"name": "markdown_document"}],
"tool_module_qualnames": {"markdown_document": "oh_markdown_tool.tool"},
Standalone usage (no agent)
MarkdownExecutor runs the operations directly. It lives in oh_markdown_tool.tool and
therefore needs the [openhands] extra (the action/observation types build on the SDK):
from pathlib import Path
from oh_markdown_tool.tool import MarkdownAction, MarkdownExecutor
# Initialize executor with workspace directory
executor = MarkdownExecutor(workspace_dir=Path("."))
# Get document overview
action = MarkdownAction(command="overview", file="design.md")
result = executor.execute(action)
print(result.content)
# Renumber sections
action = MarkdownAction(command="renumber", file="design.md")
result = executor.execute(action)
print(f"Renumbered {result.sections_renumbered} sections")
# Update table of contents
action = MarkdownAction(command="toc_update", file="design.md", depth=3)
result = executor.execute(action)
print(f"TOC updated with {result.toc_entries} entries")
For SDK-free, lower-level access, import the core classes directly (no [openhands]
extra needed):
from oh_markdown_tool import MarkdownParser, SectionNumberer, TocManager
Document Conventions
Section Numbering
- Document title uses
#(h1) and is unnumbered - Top-level sections use
##(h2):## 1. Introduction - Subsections are numbered hierarchically:
### 1.1 Purpose,#### 1.1.1 Detail
Table of Contents
- TOC section uses
## Table Of Contents(unnumbered, case-insensitive) - Appears after document title, before first numbered section
- Depth is configurable (default: 3 levels)
Section References
Sections can be referenced by:
- Number:
"3.2"(current numbering in document) - Title:
"Implementation Plan"(exact title match)
Available Commands
| Command | Description | Parameters |
|---|---|---|
overview |
Show document structure | file |
validate |
Check structure consistency | file |
renumber |
Fix section numbering | file |
toc_update |
Generate/update TOC | file, depth (default: 3) |
toc_remove |
Remove TOC | file |
move |
Move a section | file, section, position, target |
insert |
Insert new section | file, heading, level, position, target |
delete |
Delete section | file, section |
promote |
Increase heading level | file, section |
demote |
Decrease heading level | file, section |
rewrap |
Rewrap paragraphs | file, width (default: 80) |
lint |
Check for issues | file |
fix |
Auto-fix issues | file |
cleanup |
Full cleanup | file, width, depth |
Architecture
The tool is composed of several specialized components:
oh_markdown_tool/
├── parser.py # Parse markdown into section tree
├── numbering.py # Validate and renumber sections
├── toc.py # Table of contents management
├── operations.py # Section operations (move, insert, delete, etc.)
├── formatter.py # Formatting, linting, and fixing
└── tool.py # OpenHands SDK tool integration
Development
Setup
# Clone the repository
git clone https://github.com/jpshackelford/oh-markdown-tool.git
cd oh-markdown-tool
# Install with dev dependencies
pip install -e ".[dev]"
# Or with uv
uv pip install -e ".[dev]"
Running Tests
pytest
With coverage:
pytest --cov=oh_markdown_tool --cov-report=html
Code Quality
# Format and lint
ruff check .
ruff format .
Dependencies
Core:
openhands-sdk>=1.19.0- OpenHands SDK integrationpydantic>=2.0.0- Data validationmdformat>=0.7- Paragraph rewrappingpymarkdownlnt>=0.9- Linting and auto-fixingrich>=13.0.0- Terminal formatting
License
MIT License - see LICENSE file for details
Credits
Originally developed as part of the lxa project.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Commit Messages
This project uses Conventional Commits and Release Please for automated releases. Please use the following commit message format:
feat: add new feature # New features (minor version bump)
fix: correct bug # Bug fixes (patch version bump)
docs: update documentation # Documentation changes
refactor: improve code # Code refactoring
test: add tests # Test changes
chore: update dependencies # Maintenance tasks
Breaking changes should include ! or BREAKING CHANGE: in the footer:
feat!: redesign API
See PUBLISHING.md for details on the release process.
Automated Code Review
This repository uses OpenHands for automated PR reviews. When you open a PR:
- ✅ Automated review with direct, honest feedback 🔥
- ✅ Code quality critique
- ✅ Best practices enforcement
Reviews are roasted style - expect critical, no-nonsense feedback. See .github/OPENHANDS_REVIEW.md for details.
Development Guidelines
Please see CONTRIBUTING.md for detailed contribution guidelines.
Metadata
Release files for oh-markdown-tool 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oh_markdown_tool-0.2.1.tar.gz | 65.5 kB | With provenance | Details for oh_markdown_tool-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oh_markdown_tool-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for oh_markdown_tool-0.2.1-py3-none-any.whl |
Total release size: 91.9 kB
Release files / oh_markdown_tool-0.2.1.tar.gz
| Download URL | oh_markdown_tool-0.2.1.tar.gz |
|---|---|
| Size | 65.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
025311dff64c4fffcb0413e60fe35f7d618a1e5669245a83dce2d2da7c844903
|
|
BLAKE2b-256 checksum How to use checksums |
474ea8492a45af7b11b29497ce44fe7e20672e374d01a522d1b05400414e6857
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 6, 2026.
Transparency logRelease files / oh_markdown_tool-0.2.1-py3-none-any.whl
| Download URL | oh_markdown_tool-0.2.1-py3-none-any.whl |
|---|---|
| Size | 26.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bac22a32815532467844748b79cbbae9f70d258ad4f00e44de775256a3bfef8d
|
|
BLAKE2b-256 checksum How to use checksums |
fa93fcaa997bbebefab531d1f4b293d39ecd646eae4d71ccb84d9a3c8c732f51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 6, 2026.
Transparency logSecurity for oh-markdown-tool 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for oh_markdown_tool-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.