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 (or any other PyPI supported README format), 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.get_help()"
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.convert_file(Path("MyNotes.adoc"))

Output the converted file to the given location

from pathlib import Path

import pydowndoc

pydowndoc.convert_file(Path("MyNotes.adoc"), output_location=Path("path/to/output.md"))

Retrieve the converted file as a string

from pathlib import Path

import pydowndoc

converted_file_content: str = pydowndoc.convert_file(
    Path("MyNotes.adoc"), output_location=pydowndoc.OUTPUT_CONVERSION_TO_STRING,
)

Convert an in-memory string

from pathlib import Path

import pydowndoc

original_content: str = ...

converted_content: str = pydowndoc.convert_string(original_content)

Use an alternative conversion backend

from pathlib import Path

import pydowndoc
from pydowndoc.conversion_backends import PandocMultiMarkdownConversionBackend

pydowndoc.convert_file(Path("MyNotes.adoc"), backend=PandocMultiMarkdownConversionBackend)

Retrieve the version number of the currently installed downdoc executable

import pydowndoc

version_string: str = pydowndoc.get_version()

Tip	This project includes function docstrings and modern type annotations, allowing you to search for API functionality using your IDE or any program with Python LSP support.

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"

   2. Using an alternative conversion backend

      [tool.hatch.metadata.hooks.downdoc-readme]
      backend = "pandoc-md-mmd"

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"
backend = "pandoc-md-mmd"

Configuration Options

Option	Type	Default	Description
path	str	README.adoc	The location of the AsciiDoc file to be converted to Markdown and used as the project’s README file
backend	str	downdoc-md	The conversion backend used to convert from AsciiDoc to any other PyPI supported README format. Supported Conversion Backends downdoc-md Markdown converted by downdoc pandoc-md Pandoc’s Markdown converted by Pandoc & Asciidoctor (via DocBook) pandoc-multi-md MultiMarkdown converted by Pandoc & Asciidoctor (via DocBook) pandoc-php-md-extra PHP Markdown Extra converted by Pandoc & Asciidoctor (via DocBook) pandoc-txt Plaintext converted by Pandoc & Asciidoctor (via DocBook) pandoc-rst reStructuredText converted by Pandoc & Asciidoctor (via DocBook)

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 distributed under the Apache-2.0 licence.