Pydowndoc 1.0.1

Python wrapper for converting/reducing AsciiDoc files back to Markdown.

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

uvx Pydowndoc --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

python -m pip install Pydowndoc

CLI Usage

If installed using {labelled-url-pip}, or as a {url-uv-wiki-tools-installing}[permenantly installed uv tool], an alias to the original command name (`+downdoc+`) is available

downdoc --version

Get the currently installed version

uvx Pydowndoc --version

Run using the command alias

uvx --from Pydowndoc downdoc --version

Output the help message

uvx Pydowndoc --help

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

uvx Pydowndoc MyNotes.adoc

Output the converted file to the given filename

uvx Pydowndoc MyNotes.adoc -o output.md

Output the converted file to stdout

uvx Pydowndoc MyNotes.adoc -o -

Read the input AsciiDoc file from stdin

cat MyNotes.adoc | uvx Pydowndoc - -o MyNotes.md

API Usage

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

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()

Using 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

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

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.