# Pydowndoc
Rapidly convert your [AsciiDoc](https://asciidoc.org) files to [Markdown](https://wikipedia.org/wiki/Markdown), using [Python](https://python.org)
A [Python](https://python.org) wrapper around the latest-built binary of [downdoc](https://github.com/opendevise/downdoc); a rapid [AsciiDoc](https://asciidoc.org) to [Markdown](https://wikipedia.org/wiki/Markdown) converter.
## Why Use Pydowndoc?
* Run [downdoc](https://github.com/opendevise/downdoc) from the CLI within your [virtual environment](https://docs.python.org/3/tutorial/venv)
* Use [PyPI](https://pypi.org) as the single installation location of your [Python](https://python.org) project tooling
* Use [pydowndoc/__init__.py](pass:macros)[the API] to convert files using your own [Python](https://python.org) code/scripts
* Use the [Hatch](https://hatch.pypa.io) plugin to convert your project’s README.adoc file to [Markdown](https://wikipedia.org/wiki/Markdown), when building your package
## Installation
**Run as a [uv tool](https://docs.astral.sh/uv/guides/tools) (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](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**
uv add Pydowndoc[bin]
**[Install permanently as a uv tool](https://docs.astral.sh/uv/guides/tools#installing-tools)**
uv tool install Pydowndoc-bin
**Install using [pip](https://pip.pypa.io) after [creating a virtual environment](https://docs.python.org/3/tutorial/venv)**
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](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras).
**Installing **without** the `[bin]` extra on a system where `downdoc` is not already installed will not work**
```console
$ 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](https://peps.python.org/pep-0771) is finalised, the default install will include the `[bin]` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras), and using the `downdoc` binary already installed on your system will require opting-out from including the `[bin]` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras).
## CLI Usage
These commands will only work correctly after the `downdoc` binary has been installed, either as a system binary or using the `[bin]` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras).
See [Installing the `downdoc` Binary](#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`)**
```python
from pathlib import Path
import pydowndoc
pydowndoc.run(Path("MyNotes.adoc"))
```
**Retrieve the converted file as a string**
```python
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)**
```python
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
```toml
[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
```toml
[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](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras) in your package’s build dependencies.
3. Include the hook name within `[tool.hatch.metadata.hooks]` to enable [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)-file conversion
```toml
[tool.hatch.metadata.hooks.downdoc-readme]
```
or
```toml
[tool.hatch.metadata.hooks]
downdoc-readme = {}
```
1. Using a path to a custom [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file
```toml
[tool.hatch.metadata.hooks.downdoc-readme]
path = "README2.adoc"
```
<details>
<summary>A full example of a `+pyproject.toml+` file</summary>
```toml
[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"
```
</details>
### Configuration Options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `str` | `README.adoc` | The location of your AsciiDoc to be converted to [Markdown](https://wikipedia.org/wiki/Markdown), to be used as the project’s [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file |
## Upgrading
**If [installed as a uv tool](https://docs.astral.sh/uv/guides/tools#upgrading-tools)**
uv tool upgrade Pydowndoc-bin
**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**
uv sync --upgrade-package Pydowndoc
**If installed using [pip](https://pip.pypa.io)**
path/to/venv/python -m pip install --upgrade Pydowndoc
## Uninstallation
**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**
uv remove Pydowndoc
**If installed as a [uv tool](https://docs.astral.sh/uv/guides/tools)**
uv tool uninstall Pydowndoc-bin
**If installed with [pip](https://pip.pypa.io)**
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](https://github.com/CarrotManMatt/Pydowndoc/issues).
If you have problems with the conversion process of your AsciiDoc files to Markdown, please report these [upstream](https://github.com/opendevise/downdoc/issues), directly to the [downdoc project](https://github.com/opendevise/downdoc).
### 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](https://github.com/CarrotManMatt/Pydowndoc/issues).
## Licencing
The compiled binary of the distributed downdoc software is shared under the MIT licence as described in [the upstream project’s licence file](https://github.com/opendevise/downdoc?tab=MIT-1-ov-file#readme).
All other code in this project is distrubuted under [the Apache-2.0 licence](./LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "Pydowndoc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "AsciiDoc, Hatch, Hatchling, Markdown, Python, README, build, converter, documentation, metadata, packaging, pypi, pyproject.toml",
"author": null,
"author_email": "Matt Norton <matt@carrotmanmatt.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/31/8658261be6486433a80646548df9c50b77913c2c6cb5592432c27dd1deda/pydowndoc-1.3.2.tar.gz",
"platform": null,
"description": "# Pydowndoc\n\n\n\n\n\n\n\n\n\n\n\nRapidly convert your [AsciiDoc](https://asciidoc.org) files to [Markdown](https://wikipedia.org/wiki/Markdown), using [Python](https://python.org)\n\nA [Python](https://python.org) wrapper around the latest-built binary of [downdoc](https://github.com/opendevise/downdoc); a rapid [AsciiDoc](https://asciidoc.org) to [Markdown](https://wikipedia.org/wiki/Markdown) converter.\n\n## Why Use Pydowndoc?\n\n* Run [downdoc](https://github.com/opendevise/downdoc) from the CLI within your [virtual environment](https://docs.python.org/3/tutorial/venv)\n* Use [PyPI](https://pypi.org) as the single installation location of your [Python](https://python.org) project tooling\n* Use [pydowndoc/__init__.py](pass:macros)[the API] to convert files using your own [Python](https://python.org) code/scripts\n* Use the [Hatch](https://hatch.pypa.io) plugin to convert your project\u2019s README.adoc file to [Markdown](https://wikipedia.org/wiki/Markdown), when building your package\n\n## Installation\n\n**Run as a [uv tool](https://docs.astral.sh/uv/guides/tools) (no installation necessary)**\n\nuvx --from Pydowndoc-bin -- downdoc --version\n\n**\ud83d\udca1 TIP**\\\nuv 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`.\n\n**Add to your [uv project/script\u2019s dependencies](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**\n\nuv add Pydowndoc[bin]\n\n**[Install permanently as a uv tool](https://docs.astral.sh/uv/guides/tools#installing-tools)**\n\nuv tool install Pydowndoc-bin\n\n**Install using [pip](https://pip.pypa.io) after [creating a virtual environment](https://docs.python.org/3/tutorial/venv)**\n\npath/to/venv/python -m pip install Pydowndoc[bin]\n\n### Installing the `downdoc` Binary\n\nPydowndoc assumes by default that you wish to use the `downdoc` binary already installed on your system (E.g. using your system\u2019s package manager).\nInstalling the PyPI package `Pydowndoc` will only install the Python compatibility layer for downdoc.\n\nIf you wish to _also_ install the `downdoc` binary itself, please install using the `[bin]` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras).\n\n**Installing **without** the `[bin]` extra on a system where `downdoc` is not already installed will not work**\n\n```console\n$ uvx --with Pydowndoc python -c \"import pydowndoc; pydowndoc.run()\"\nOSError: The downdoc executable could not be found. Ensure it is installed (E.g `uv add Pydowndoc[bin]`).\n```\n\n**\ud83d\udccc NOTE**\\\nOnce [PEP 771](https://peps.python.org/pep-0771) is finalised, the default install will include the `[bin]` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras), and using the `downdoc` binary already installed on your system will require opting-out from including the `[bin]` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras).\n\n## CLI Usage\n\nThese commands will only work correctly after the `downdoc` binary has been installed, either as a system binary or using the `[bin]` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras).\nSee [Installing the `downdoc` Binary](#installing-the-`downdoc`-binary) for more information.\n\n**Display the current version number (useful to validate that installation was successful)**\n\ndowndoc --version\n\n**Display the help message**\n\ndowndoc --help\n\n**Convert a given file (the same filename will be retained, with file-extension changed to `.md`)**\n\ndowndoc MyNotes.adoc\n\n**Output the converted file to the given filename & path**\n\ndowndoc MyNotes.adoc -o path/to/output.md\n\n**Output the converted file to stdout**\n\ndowndoc MyNotes.adoc -o -\n\n**Read the input AsciiDoc file from stdin**\n\ncat MyNotes.adoc | downdoc - -o MyNotes.md\n\n## API Usage\n\n**Convert a given file (the same filename will be retained, with file-extension changed to `.md`)**\n\n```python\nfrom pathlib import Path\n\nimport pydowndoc\n\npydowndoc.run(Path(\"MyNotes.adoc\"))\n```\n\n**Retrieve the converted file as a string**\n\n```python\nfrom pathlib import Path\n\nimport pydowndoc\n\nconverted_file_contents: str = pydowndoc.run(\n Path(\"MyNotes.adoc\"),\n output=\"-\",\n process_capture_output=True,\n).stdout.decode()\n```\n\n**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)**\n\n```python\nfrom pathlib import Path\n\nimport pydowndoc\n\npydowndoc.run(\n Path(\"MyNotes.adoc\"),\n output=Path(\"path/to/output.md\"),\n process_check_return_code=True,\n)\n```\n\n## Use as a Hatch build hook\n\n1. Ensure the `readme` field is added to your `project.dynamic` list within your `pyproject.toml` file\n\n ```toml\n [project]\n name = \"my-cool-project\"\n version = \"0.1.0\"\n dynamic = [\"readme\"]\n ```\n2. Set up your build backend, within your `pyproject.toml` file, adding `Pydowndoc[bin]` as a build dependency\n\n ```toml\n [build-system]\n build-backend = \"hatchling.build\"\n requires = [\"hatchling\", \"Pydowndoc[bin]\"]\n ```\n\n **\ud83d\udca1 TIP**\\\n 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](https://packaging.python.org/en/latest/specifications/dependency-specifiers#extras) in your package\u2019s build dependencies.\n3. Include the hook name within `[tool.hatch.metadata.hooks]` to enable [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)-file conversion\n\n ```toml\n [tool.hatch.metadata.hooks.downdoc-readme]\n ```\n\n or\n\n ```toml\n [tool.hatch.metadata.hooks]\n downdoc-readme = {}\n ```\n 1. Using a path to a custom [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file\n\n ```toml\n [tool.hatch.metadata.hooks.downdoc-readme]\n path = \"README2.adoc\"\n ```\n\n<details>\n<summary>A full example of a `+pyproject.toml+` file</summary>\n\n```toml\n[project]\nname = \"my-cool-project\"\nversion = \"0.1.0\"\ndynamic = [\"readme\"]\n\n[build-system]\nbuild-backend = \"hatchling.build\"\nrequires = [\"hatchling\", \"Pydowndoc[bin]\"]\n\n[tool.hatch.metadata.hooks.downdoc-readme]\npath = \"README2.adoc\"\n```\n</details>\n\n### Configuration Options\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `path` | `str` | `README.adoc` | The location of your AsciiDoc to be converted to [Markdown](https://wikipedia.org/wiki/Markdown), to be used as the project\u2019s [README](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) file |\n\n## Upgrading\n\n**If [installed as a uv tool](https://docs.astral.sh/uv/guides/tools#upgrading-tools)**\n\nuv tool upgrade Pydowndoc-bin\n\n**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**\n\nuv sync --upgrade-package Pydowndoc\n\n**If installed using [pip](https://pip.pypa.io)**\n\npath/to/venv/python -m pip install --upgrade Pydowndoc\n\n## Uninstallation\n\n**If added as a [uv project dependency](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**\n\nuv remove Pydowndoc\n\n**If installed as a [uv tool](https://docs.astral.sh/uv/guides/tools)**\n\nuv tool uninstall Pydowndoc-bin\n\n**If installed with [pip](https://pip.pypa.io)**\n\npath/to/venv/python -m pip uninstall Pydowndoc\n\n## Reporting Issues\n\nIf 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](https://github.com/CarrotManMatt/Pydowndoc/issues).\n\nIf you have problems with the conversion process of your AsciiDoc files to Markdown, please report these [upstream](https://github.com/opendevise/downdoc/issues), directly to the [downdoc project](https://github.com/opendevise/downdoc).\n\n### Windows & macOS Wheels\n\nWindows and macOS wheels are provided to enable use of this project on non-linux hosts.\nHowever, these versions have not had the same level of testing as the linux version.\nTherefore, if you encounter any bugs with these other versions, report them on [the GitHub issues tracker for this project](https://github.com/CarrotManMatt/Pydowndoc/issues).\n\n## Licencing\n\nThe compiled binary of the distributed downdoc software is shared under the MIT licence as described in [the upstream project\u2019s licence file](https://github.com/opendevise/downdoc?tab=MIT-1-ov-file#readme).\n\nAll other code in this project is distrubuted under [the Apache-2.0 licence](./LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "Python wrapper for converting/reducing AsciiDoc files back to Markdown.",
"version": "1.3.2",
"project_urls": {
"Issues": "https://github.com/CarrotManMatt/Pydowndoc/issues",
"Repository": "https://github.com/CarrotManMatt/Pydowndoc"
},
"split_keywords": [
"asciidoc",
" hatch",
" hatchling",
" markdown",
" python",
" readme",
" build",
" converter",
" documentation",
" metadata",
" packaging",
" pypi",
" pyproject.toml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f4a479d1c6689052ee448fa72df6d0493631dca039d76da3f20b041c92447dae",
"md5": "4dc20b6c36e53c06dc4c82b5a1d88c01",
"sha256": "86fd3f0db3d15f4fec7984089ea81b67012a8f44351674cae6285c051238901e"
},
"downloads": -1,
"filename": "pydowndoc-1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4dc20b6c36e53c06dc4c82b5a1d88c01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11952,
"upload_time": "2025-07-10T01:33:18",
"upload_time_iso_8601": "2025-07-10T01:33:18.288981Z",
"url": "https://files.pythonhosted.org/packages/f4/a4/79d1c6689052ee448fa72df6d0493631dca039d76da3f20b041c92447dae/pydowndoc-1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c3318658261be6486433a80646548df9c50b77913c2c6cb5592432c27dd1deda",
"md5": "83afbcb846fee4a4f3c2d5184e5a5a25",
"sha256": "b0ed76b75fcbcbe60175ba8a24d436c8295f927f6a0832982cb888b5097b4d6c"
},
"downloads": -1,
"filename": "pydowndoc-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "83afbcb846fee4a4f3c2d5184e5a5a25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12810,
"upload_time": "2025-07-10T01:33:19",
"upload_time_iso_8601": "2025-07-10T01:33:19.378042Z",
"url": "https://files.pythonhosted.org/packages/c3/31/8658261be6486433a80646548df9c50b77913c2c6cb5592432c27dd1deda/pydowndoc-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 01:33:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CarrotManMatt",
"github_project": "Pydowndoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pydowndoc"
}
JSON
