Pydowndoc

Rapidly convert your AsciiDoc files to Markdown, using Python

A Python wrapper around the latest-built binary of downdoc; a rapid AsciiDoc to Markdown converter.

Features

• Use PyPI as the single installation location of your Python project tooling

• Run downdoc from the CLI within your virtual environment

• Use the API to convert files using your own Python code/scripts

• Use the Hatch plugin to convert your project’s README.adoc file to Markdown, when building your package

Installation

Run as a uv tool (no installation necessary)

uvx --from Pydowndoc -- downdoc --version

Add to your uv project/script’s dependencies

uv add Pydowndoc

Install permenantly as a uv tool

uv tool install Pydowndoc

Install using pip

path/to/venv/python -m pip install Pydowndoc

CLI Usage

Warning

These commands will only work correctly either after installation as a permenant uv tool, or after activating a virtual environment with Pydowndoc installed. Replace the command name downdoc with uvx --from Pydowndoc -- downdoc, to run any of the following commands in an ephemeral envrionment.

Get the currently installed version

downdoc --version

Output the help message

downdoc --help

Convert a given file (filename will be kept the same, with .md file-extension)

downdoc MyNotes.adoc

Output the converted file to the given filename

downdoc MyNotes.adoc -o output.md

Output the converted file to stdout

downdoc MyNotes.adoc -o -

Read the input AsciiDoc file from stdin

cat MyNotes.adoc | downdoc - -o MyNotes.md

API Usage

Convert a given file (the filename will be kept the same, with a .md file-extension)

from pathlib import Path

import pydowndoc

pydowndoc.run(Path("MyNotes.adoc"))

Retrieve the converted file as a string

from pathlib import Path

import pydowndoc

converted_file_contents: str = pydowndoc.run(
    Path("MyNotes.adoc"),
    output="-",
    process_capture_output=True,
).stdout.decode()

Ensure the conversion process executes successfully

from pathlib import Path

import pydowndoc

converted_file_contents: str = pydowndoc.run(
    Path("MyNotes.adoc"),
    output=Path("output.md"),
    process_check_return_code=True,
).stdout.decode()

Use as a Hatch build hook

1. Ensure the readme field is added to your project.dynamic list within your pyproject.toml file

   [project]
   name = "my-cool-project"
   version = "0.1.0"
   dynamic = ["readme"]

2. Set up your build backend, within your pyproject.toml file

   [build-system]
   build-backend = "hatchling.build"
   requires = ["hatchling", "Pydowndoc"]

3. Include the hook name, so that processing ocurrs

   [tool.hatch.metadata.hooks.downdoc-readme]

   1. Using a path to a custom README file

      [tool.hatch.metadata.hooks.downdoc-readme]
      path = "README2.adoc"

A full example of a pyproject.toml file

[project]
name = "my-cool-project"
version = "0.1.0"
dynamic = ["readme"]

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling", "Pydowndoc"]

[tool.hatch.metadata.hooks.downdoc-readme]
path = "README2.adoc"

Configuration Options

Option	Type	Default	Description
path	str	README.adoc	The location of the file to convert to Markdown, to be used as the project’s README file

Upgrading

If installed as a uv tool

uv tool upgrade Pydowndoc

If added as a uv project dependency

uv sync --upgrade-package Pydowndoc

If installed using pip

path/to/venv/python -m pip install --upgrade Pydowndoc

Uninstallation

If added as a uv project dependency

uv remove Pydowndoc

If installed as a uv tool

uv tool uninstall Pydowndoc

If installed with pip

path/to/venv/python -m pip uninstall Pydowndoc

Reporting Issues

If there are issues with the Python API for this package, or you are encountering installation problems, please report these to the GitHub issues tracker for this project.

If you have problems with the conversion process of your AsciiDoc files to Markdown, please report these upstream, directly to the downdoc project.

Licencing

The compiled binary of the distributed downdoc software is shared under the MIT licence as described in the upstream project’s licence file.

All other code in this project is distrubuted under the Apache-2.0 licence.