User macro that allows AsciiDoc (Asciidoctor) blocks inside Confluence pages.
Note
|
This README will render better if you view the RAW file in conjunction with the 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 asciidoctor.js javascript library.
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
andDefinition
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 Work-around for Confluence Whitespace Issues for more information. |
The velocity template source code is available in the adoc.velocity file on GitHub.
The macro uses the Foundation Asciidoctor styles by default to present the code when it is saved.
<link type="text/css" rel="stylesheet" href="//www.norganna.com/cdn/css/adoc-foundation.css" media="all">
If you want to get the stock Confluence Look and Feel, change the css filename to adoc-confluence.css
instead.
<link type="text/css" rel="stylesheet" href="//www.norganna.com/cdn/css/adoc-confluence.css" media="all">
If you remove this class completely you will be left with a mess due to the heavy use of container <div>s in the Asciidoctor HTML5 output.
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 Work-around for Confluence Whitespace Issues.
- Use the Raw Macro
-
Paste your Asciidoctor text between the
{adoc}
tag as suggested in Raw Macro Usage.
{adoc}
= Hello, AsciiDoc!
Doc Writer <doc@example.com>
An introduction to http://asciidoc.org[AsciiDoc].
== Header 2
Content content.
* List item 1
* List item 2
{adoc}
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
dialog to work around this issue.
-
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.
-
Type {adoc} and press enter.
-
Paste your AsciiDoc code and press enter.
-
Type {adoc} again at the end.
NoteThe 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.
Note
|
Click the link if you are viewing on GitHub. Inline include works locally. |