gitbucket-asciidoctor-plugin

gitbucket-asciidoctor-plugin copied to clipboard

= gitbucket-asciidoctor-plugin :plugin-version: 1.1.0 :scala-version: 2.13 :gitbucket-bincompat-version: 4.32.0 :link-github: https://github.com/asciidoctor/gitbucket-asciidoctor-plugin

image:{link-github}/actions/workflows/build.yml/badge.svg["Build Status (build.yml)", link="{link-github}/actions/workflows/build.yml"] image:https://badges.gitter.im/asciidoctor/gitbucket-asciidoctor-plugin.svg["Gitter Chat", link="https://gitter.im/asciidoctor/gitbucket-asciidoctor-plugin"]

A https://github.com/gitbucket/gitbucket[GitBucket] plug-in that provides AsciiDoc rendering capabilities. All .adoc (and also the deprecated .asciidoc and .ad suffix) files will be automatically rendered as AsciiDoc, supporting most features of the http://asciidoctor.org/[Asciidoctor project], including rendering of a table of contents.

== Download

You can download a precompiled version from the {link-github}/releases[Release page].

== Build from source

.With sbt

sbt assembly

.Or with GNU Make

make build

You will find the packages plugin under target/scala_2.13/gitbucket-asciidoctor-plugin-gitbucket_{gitbucket-bincompat-version}-{plugin-version}.jar

== Installation

Download gitbucket-asciidoctor-plugin-gitbucket_{gitbucket-bincompat-version}-{plugin-version}.jar or build the assembly package JAR file from source and copy it into GITBUCKET_HOME/plugins. If you have older versions of this plugin in this directory, you must delete them. Then restart GitBucket. That's it.

== Local Test Server

You can start a local GitBucket instance with this plugin already installed by running:

make localServer

Point your browser to http://localhost:8080. The administrator login is root/root.

== Configuration

=== Asciidoctor builtin attributes

You can tweak the asciidoctor rendering engine by customizing the http://asciidoctor.org/docs/user-manual/#builtin-attributes[builtin attributes]. Simple edit the properties file at GITBUCKET_HOME/asciidoctor.properties.

.Example: Set toc attribute in the GITBUCKET_HOME/asciidoctor.properties file [source,properties]

toc=preamble

== License

This plugin is published under the Apache License, version 2.0.

== ChangeLog

=== gitbucket-asciidoctor-plugin 1.1.0 - 2019-11-19

• Support fot GitBucket 4.32.0
• Updated dependencies
• Added include support (for files in the same repository)

See https://github.com/asciidoctor/gitbucket-asciidoctor-plugin/milestone/6?closed=1[list of closed issues and pull requests].

=== gitbucket-asciidoctor-plugin 1.0.2 - 2017-03-08

• Added support to provide attributes to the asciidoctor engine via properties file in gitbucket directory.

=== gitbucket-asciidoctor-plugin 1.0.1 - 2016-06-01

• Post-process src attribute of generated <img> tags to point to raw image resource.

=== gitbucket-asciidoctor-plugin 1.0.0 - 2016-05-03

• Set the outfilesuffix attribute to .adoc to properly support xref's.
• Introduced new attribute gitbucket-branch which contains the current selected git branch (or hash).
• Requires GitBucket 4.0 or newer.

=== gitbucket-asciidoctor-plugin 0.1.1 - 2016-02-02

• Updated some dependency versions.
• Set the attributes env=gitbucket and env-gitbucket=true so that rendered pages can apply environment specific logic.

=== gitbucket-asciidoctor-plugin 0.1.0 - 2015-10-06

• Initial release