# Getting started
Use AsciiDoc with Material for MkDocs.
> [!IMPORTANT]
> This package is an early release. The API may change without notice, and stability is not guaranteed. Use in production environments is not recommended. Feedback and testing are welcome.
This MkDocs plugin replaces the MkDocs default Markdown processor with [Asciidoctor](https://asciidoctor.org/) for AsciiDoc files, allowing you to write documentation in AsciiDoc while keeping full compatibility with Material for MkDocs.
The plugin uses Asciidoctor to build and then adjusts the output it to match MkDocs conventions.
The plugin ships some CSS/JS/RB and optionally injects "edit this page" links for included AsciiDoc modules when `repo_url` and `edit_uri` are configured.
Supports hot reload on the development server for all AsciiDoc source files when writing.
Asciidoctor attributes can be injected via the `mkdocs.yml`.
## Using mkdocs-asciidoctor-backend
```bash
pip install mkdocs-asciidoctor-backend --upgrade --pre
```
> [!IMPORTANT]
>
> - MkDocs expects docs source in a `docs/` folder. See [Strategy for including docs from repository root](https://github.com/mkdocs/mkdocs/discussions/3062) for further discussion.
>
> - For larger doc sets, set up a `nav` element in the `mkdocs.yml`, and optionally a root `docs/index.adoc` file. See [nav](https://www.mkdocs.org/user-guide/configuration/#nav) for more details.
>
> - Asciidoctor xrefs might require you to set `relfileprefix` either globally in `mkdocs.yml` or per section/assembly file.
The following example `mkdocs.yml` can be dropped into the root of an existing AsciiDoc project.
```yaml
site_name: Example
repo_url: https://github.com/example/repo
repo_name: example-repo
edit_uri: edit/main/
theme:
name: material
features:
- content.action.edit
- content.code.annotate
- content.code.copy
- content.code.select
- navigation.footer
- navigation.top
- navigation.tracking
- palette.toggle
- search.highlight
- search.suggest
- toc.follow
- toc.sticky
palette:
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/toggle-switch
name: Switch to light mode
exclude_docs: |
partials/**
snippets/**
modules/**
plugins:
- search
- asciidoctor_backend:
edit_includes: true
fail_on_error: false
ignore_missing: true
safe_mode: safe
attributes:
imagesdir: images
showtitle: true
sectanchors: true
sectlinks: true
icons: font
idprefix: ""
idseparator: "-"
outfilesuffix: .html
source-highlighter: rouge
```
A demo docs site is published here: https://aireilly.github.io/mkdocs-asciidoctor-backend/
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-asciidoctor-backend",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "mkdocs, asciidoctor, plugin",
"author": "Aidan Reilly",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7c/9d/89d9a7eac676314e6505ded7d6e01d4fac137703fbd83b930b986e107eb8/mkdocs_asciidoctor_backend-0.1.12.tar.gz",
"platform": null,
"description": "# Getting started\n\nUse AsciiDoc with Material for MkDocs.\n\n> [!IMPORTANT]\n> This package is an early release. The API may change without notice, and stability is not guaranteed. Use in production environments is not recommended. Feedback and testing are welcome.\n\nThis MkDocs plugin replaces the MkDocs default Markdown processor with [Asciidoctor](https://asciidoctor.org/) for AsciiDoc files, allowing you to write documentation in AsciiDoc while keeping full compatibility with Material for MkDocs.\n\nThe plugin uses Asciidoctor to build and then adjusts the output it to match MkDocs conventions.\nThe plugin ships some CSS/JS/RB and optionally injects \"edit this page\" links for included AsciiDoc modules when `repo_url` and `edit_uri` are configured.\n\nSupports hot reload on the development server for all AsciiDoc source files when writing.\n\nAsciidoctor attributes can be injected via the `mkdocs.yml`.\n\n## Using mkdocs-asciidoctor-backend\n\n```bash\npip install mkdocs-asciidoctor-backend --upgrade --pre\n```\n\n> [!IMPORTANT]\n>\n> - MkDocs expects docs source in a `docs/` folder. See [Strategy for including docs from repository root](https://github.com/mkdocs/mkdocs/discussions/3062) for further discussion.\n> \n> - For larger doc sets, set up a `nav` element in the `mkdocs.yml`, and optionally a root `docs/index.adoc` file. See [nav](https://www.mkdocs.org/user-guide/configuration/#nav) for more details.\n> \n> - Asciidoctor xrefs might require you to set `relfileprefix` either globally in `mkdocs.yml` or per section/assembly file.\n\nThe following example `mkdocs.yml` can be dropped into the root of an existing AsciiDoc project. \n\n```yaml\nsite_name: Example\nrepo_url: https://github.com/example/repo\nrepo_name: example-repo\nedit_uri: edit/main/\n\ntheme:\n name: material\n features:\n - content.action.edit\n - content.code.annotate\n - content.code.copy\n - content.code.select\n - navigation.footer\n - navigation.top\n - navigation.tracking\n - palette.toggle\n - search.highlight\n - search.suggest\n - toc.follow\n - toc.sticky\n palette:\n - scheme: default\n primary: indigo\n accent: indigo\n toggle:\n icon: material/toggle-switch-off-outline\n name: Switch to dark mode\n - scheme: slate\n primary: indigo\n accent: indigo\n toggle:\n icon: material/toggle-switch\n name: Switch to light mode\n\nexclude_docs: |\n partials/**\n snippets/**\n modules/**\n\nplugins:\n - search\n - asciidoctor_backend:\n edit_includes: true\n fail_on_error: false\n ignore_missing: true\n safe_mode: safe\n attributes:\n imagesdir: images\n showtitle: true\n sectanchors: true\n sectlinks: true\n icons: font\n idprefix: \"\"\n idseparator: \"-\"\n outfilesuffix: .html\n source-highlighter: rouge\n```\n\nA demo docs site is published here: https://aireilly.github.io/mkdocs-asciidoctor-backend/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Asciidoctor backend for MkDocs",
"version": "0.1.12",
"project_urls": {
"Homepage": "https://github.com/aireilly/mkdocs-asciidoctor-backend",
"Issues": "https://github.com/aireilly/mkdocs-asciidoctor-backend/issues",
"Source": "https://github.com/aireilly/mkdocs-asciidoctor-backend"
},
"split_keywords": [
"mkdocs",
" asciidoctor",
" plugin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "59c83d0dfd595dbb40e54cf448c15fdf9fe8d66784241c9e3bb3d4b4843f5701",
"md5": "2a848bfb13e3fc9e4601bf3be10efbac",
"sha256": "997046f604080d03f9b2cb2b4ff0c8c45e8147a40b9f5c3e91768716992cbc32"
},
"downloads": -1,
"filename": "mkdocs_asciidoctor_backend-0.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a848bfb13e3fc9e4601bf3be10efbac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21599,
"upload_time": "2025-10-08T12:43:12",
"upload_time_iso_8601": "2025-10-08T12:43:12.778748Z",
"url": "https://files.pythonhosted.org/packages/59/c8/3d0dfd595dbb40e54cf448c15fdf9fe8d66784241c9e3bb3d4b4843f5701/mkdocs_asciidoctor_backend-0.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7c9d89d9a7eac676314e6505ded7d6e01d4fac137703fbd83b930b986e107eb8",
"md5": "a73b5223d4822a3f4673ad982bd0151c",
"sha256": "fc2a37d037720badcd780489bb4ba2fbd9ca2b898b3e14cfaa47ff0011706cd5"
},
"downloads": -1,
"filename": "mkdocs_asciidoctor_backend-0.1.12.tar.gz",
"has_sig": false,
"md5_digest": "a73b5223d4822a3f4673ad982bd0151c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 186940,
"upload_time": "2025-10-08T12:43:13",
"upload_time_iso_8601": "2025-10-08T12:43:13.717065Z",
"url": "https://files.pythonhosted.org/packages/7c/9d/89d9a7eac676314e6505ded7d6e01d4fac137703fbd83b930b986e107eb8/mkdocs_asciidoctor_backend-0.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 12:43:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aireilly",
"github_project": "mkdocs-asciidoctor-backend",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-asciidoctor-backend"
}
JSON
