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.

Why Use Pydowndoc?

• Run downdoc from the CLI within your virtual environment

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

• 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-bin -- downdoc --version

Tip	uv will warn you that the downdoc binary is not directly provided by the Pydowndoc[bin] package, so we suggest to use --from Pydowndoc-bin when running downdoc using uvx or uv tool.

Add to your uv project/script’s dependencies

uv add Pydowndoc[bin]

Install permanently as a uv tool

uv tool install Pydowndoc-bin

Install using pip after creating a virtual environment

path/to/venv/python -m pip install Pydowndoc[bin]

Installing the downdoc Binary

Pydowndoc assumes by default that you wish to use the downdoc binary already installed on your system (E.g. using your system’s package manager). Installing the PyPI package Pydowndoc will only install the Python compatibility layer for downdoc.

If you wish to also install the downdoc binary itself, please install using the [bin] extra.

Installing without the [bin] extra on a system where downdoc is not already installed will not work

$ uvx --with Pydowndoc python -c "import pydowndoc; pydowndoc.run()"
OSError: The downdoc executable could not be found. Ensure it is installed (E.g `uv add Pydowndoc[bin]`).

Note	Once PEP 771 is finalised, the default install will include the [bin] extra, and using the downdoc binary already installed on your system will require opting-out from including the [bin] extra.

CLI Usage

Warning

These commands will only work correctly after the downdoc binary has been installed, either as a system binary or using the [bin] extra. See Installing the downdoc Binary for more information.

Display the current version number (useful to validate that installation was successful)

downdoc --version

Display the help message

downdoc --help

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

downdoc MyNotes.adoc

Output the converted file to the given filename & path

downdoc MyNotes.adoc -o path/to/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 same filename will be retained, with file-extension changed to .md)

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 and output the converted file to the given location (by default your code will continue execution even if conversion fails)

from pathlib import Path

import pydowndoc

pydowndoc.run(
    Path("MyNotes.adoc"),
    output=Path("path/to/output.md"),
    process_check_return_code=True,
)

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, adding Pydowndoc[bin] as a build dependency

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

   Tip	To prevent issues with users building your package that may not have the downdoc binary already installed on their system, we suggest including the [bin] extra in your package’s build dependencies.

3. Include the hook name within [tool.hatch.metadata.hooks] to enable README-file conversion

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

   or

   [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[bin]"]

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

Configuration Options

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

Upgrading

If installed as a uv tool

uv tool upgrade Pydowndoc-bin

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-bin

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 on 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.

Windows & macOS Wheels

Windows and macOS wheels are provided to enable use of this project on non-linux hosts. However, these versions have not had the same level of testing as the linux version. Therefore, if you encounter any bugs with these other versions, report them on the GitHub issues tracker for this 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.