= Asciidoctor Maven Tools (Plugin & Site Integration) // Metadata :release-version: 3.0.0 :maven-site-plugin-version: 3.12.1 // Settings :idprefix: :idseparator: - ifdef::env-github,env-browser[] :toc: preamble endif::[] ifndef::env-github[:icons: font] // URIs :project-repo: asciidoctor/asciidoctor-maven-plugin :uri-repo: https://github.com/{project-repo} :uri-asciidoc: http://asciidoc.org :uri-asciidoctor: http://asciidoctor.org :uri-examples: https://github.com/asciidoctor/asciidoctor-maven-examples :uri-maven: http://maven.apache.org :uri-license: {uri-repo}/blob/main/LICENSE.txt :uri-docs: https://docs.asciidoctor.org/maven-tools/latest :uri-project-chat: https://chat.asciidoctor.org // GitHub customization ifdef::env-github[] :badges: :tag: main :!toc-title: :tip-caption: :bulb: :note-caption: :paperclip: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]
// Badges ifdef::badges[] image:{uri-repo}/workflows/Build/badge.svg[Build Status,link={uri-repo}/actions] image:http://img.shields.io/coveralls/{project-repo}/main.svg["Coverage Status", link="https://coveralls.io/r/{project-repo}?branch=main"] image:https://maven-badges.herokuapp.com/maven-central/org.asciidoctor/asciidoctor-maven-plugin/badge.svg["Maven Central",link="https://maven-badges.herokuapp.com/maven-central/org.asciidoctor/asciidoctor-maven-plugin"] image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[project chat,link={uri-project-chat}] endif::[]
The Asciidoctor Maven Plugin is the official way to convert your {uri-asciidoc}[AsciiDoc] documentation using {uri-asciidoctor}[Asciidoctor] from an {uri-maven}[Apache Maven] build.
The conversion can happen in 2 flavors:
. as a Maven plugin: AsciiDoc files are converted at full Asciidoctor power independently from Maven site,
. as a Maven site integration: AsciiDoc files are integrated with Maven reports, which comes with a few limitations (see below for details).
Full documentations is available in the {uri-docs}[USER MANUAL], if you have questions, please drop them at the {uri-project-chat}/#narrow/stream/users[PROJECT CHAT].
ifndef::env-site[] .Translations of the document are available in the following languages:
endif::[]
== Quickstart
These are the minimal steps to convert your AsciiDoc documents to HTML with the asciidoctor-maven-plugin.
. Place your AsciiDoc sources in [.path]src/docs/asciidoc.
. Run the plugin's associated phase.
$ mvn generate-resources
If you want to generate your Maven site with Asciidoctor
. Place your AsciiDoc sources in [.path]src/site/asciidoc.
. Run the plugin's associated phase.
$ mvn site:site
== Examples
You can find examples ready to copy-paste in the {uri-examples}[Asciidoctor Maven examples] project.
== Supported version
// 1-year-old versions + most recent minor asciidoctor-maven-plugin comes in two versions with support for Maven 3.8.8+ and 3.9.x versions.
== Contributing
This plugin is an open source project made possible with the help of users and enthusiasts. To continue to be useful and to evolve, this plugin needs continuing contributions. There are multiple ways where you can help:
The {uri-docs}/project/contributing.html[Contributor Guide] will help you start with the code.
== Copyright and License
Copyright (C) 2013-2024 Jason Porter, Dan Allen, Abel Salgado Romero and the individual contributors. Use of this software is granted under the terms of the Apache License, Version 2.0.
See the {uri-license}[LICENSE] for the full license text.