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 -- 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 after creating a virtual environment

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.

Display the current version number (useful to validate that installation eas 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

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

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

[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

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.

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