Getting started
Use AsciiDoc with Material for MkDocs.
This MkDocs plugin replaces the MkDocs default Markdown processor with Asciidoctor 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
pip install mkdocs-asciidoctor-backend --upgrade --pre
The following example mkdocs.yml can be dropped into the root of an existing AsciiDoc project.
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/
2 maintainers
Metadata
2 maintainers
Release files for mkdocs-asciidoctor-backend 0.1.16
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| mkdocs_asciidoctor_backend-0.1.16.tar.gz | 204.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mkdocs_asciidoctor_backend-0.1.16-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 227.3 kB
Release files / mkdocs_asciidoctor_backend-0.1.16.tar.gz
| Download URL | mkdocs_asciidoctor_backend-0.1.16.tar.gz |
|---|---|
| Size | 204.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
640cb586beb7222680e59cfcf509ef8433d4487875acb7b04db1e78a731e52c2
|
|
BLAKE2b-256 checksum How to use checksums |
87eff1a67a22a3e633905ba387a694a1defa6156eca93ea4ed989f958fed929d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Release files / mkdocs_asciidoctor_backend-0.1.16-py3-none-any.whl
| Download URL | mkdocs_asciidoctor_backend-0.1.16-py3-none-any.whl |
|---|---|
| Size | 22.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4f04a178e3a0e8156599d966732980779c477f4d0f3cf53eb328e30ce2849fc
|
|
BLAKE2b-256 checksum How to use checksums |
7667ce52dabc45a46b31cdec4ce28bdece9b647d2970c17a7e7256a4c9882ac5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Security for mkdocs-asciidoctor-backend 0.1.16
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
