adoc-usermacro
adoc-usermacro copied to clipboard
norganna
User macro to allow AsciiDoc format content in Confluence via the asciidoctor.js engine
:sectnums: :toc: macro
= image:https://raw.githubusercontent.com/norganna/adoc-usermacro/master/adoc.png["adoc-usermacro",height=32] Asciidoctor User Macro for Confluence
User macro that allows AsciiDoc (Asciidoctor) blocks inside Confluence pages.
toc::[]
== Description
NOTE: This README will render better if you view the RAW file in conjunction with the https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia?hl=en[Chrome AsciiDoctor.js Live Preview Extension].
This macro is designed to render the AsciiDoc body content in the page whilst preserving the original markup code in the macro body, so that subsequent edits of the page can update the original code. The AsciiDoc code is rendered at page display time by the https://github.com/asciidoctor/asciidoctor.js[asciidoctor.js] javascript library.
== Installation
Install the macro through the Confluence Administrator Console.
. Open the Configuration page as an administrator.
. Select Configurations => User Macros => Create a User Macro in the left navigation panel.
. Complete the Information and Definition fields based on the information in the Code section.
. Paste the velocity template code (see below) into the Template text box.
NOTE: This macro will work better with an additional Confluence macro installed. See <<Whitespace>> for more information.
== Code
The velocity template source code is available in the https://github.com/norganna/adoc-usermacro/blob/master/adoc.velocity[adoc.velocity] file on GitHub.
== Disabling Asciidoctor Foundation Styles
The macro uses the Foundation Asciidoctor styles by default to present the code when it is saved.
If you want to get the stock Confluence Look and Feel, change the css filename to adoc-confluence.css instead.
If you remove this class completely you will be left with a mess due to the heavy use of container
== Usage
You can use this Confluence Macro multiple times per page.
Choose one of the following insertion methods:
Use the Pretty Macro::
Paste your Asciidoctor text into the code window, but be aware of the functionality in <<Whitespace>>.
Use the Raw Macro::
Paste your Asciidoctor text between the {adoc} tag as suggested in <<Raw_Macro>>.
[[Raw_Macro]] .Raw Macro Usage [source,asciidoc]
{adoc} = Hello, AsciiDoc! Doc Writer [email protected]
An introduction to http://asciidoc.org[AsciiDoc].
== Header 2
Content content.
- List item 1
- List item 2 {adoc}
[[Whitespace]] == Work-around for Confluence Whitespace Issues
You'll notice that if you paste your AsciiDoc text directly into the {adoc} pretty macro, all the meaningful whitespace is stripped out.
There's no polite way of saying this: the Confluence WYSIWYG editor is less than perfect when editing anything other than Wiki markup.
=== Use The Insert Markup Feature
Use the Insert Markup dialog to work around this issue.
.How To Load the Insert Markup dialog . Create or edit your page in Confluence. . Position your cursor at the location you want your document inserted. . Click the drop-down button in the editor toolbar denoted by a plus icon. . Select the Markup option from the drop-down menu.
.How To Insert AsciiDoc Content in Insert Markup dialog. . Type {adoc} and press enter. . Paste your AsciiDoc code and press enter. . Type {adoc} again at the end. + NOTE: The right side of the window will update with the content to be inserted. . Click the Insert button at the bottom of the dialog to complete the insertion.
.Insert AsciiDoc with the Insert Markup Function https://github.com/norganna/adoc-usermacro/blob/master/howto/paste-plaintext-with-insert-markup.mp4?raw=true[Download Video]
video::howto/paste-plaintext-with-insert-markup.mp4[width=640]
=== Use The Source Editor Plug-in
NOTE: Click the link if you are viewing on GitHub. Inline include works locally.
include::howto/paste-plaintext-with-sourceeditor-addon.adoc[lines=9..-1, leveloffset=+2]
== License
Copyright 2015, Ken Allan, MIT License.
See LICENSE file for more information.
norganna