Skip to content
Generate HTML from the Conflux markup language
Perl Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib/Text
t
.gitignore
Makefile
README.pod
TODO
dist.ini

README.pod

NAME

Text::Conflux - Convert Conflux document markup syntax to (X)HTML

SYNOPSIS

From the command line:

$ conflux < input.txt > output.html

From Perl code:

use Text::Conflux;

my $c = Text::Conflux->new(
    {
        header_toggles  => 1,
        stylesheet      => qq[/path/to/file.css],
        audience        => 'enterprise_users',
        title           => 'Page Title',
        image_dir       => '/path/to/images',
        include_dir     => '/path/to/includes',
        code_sample_dir => '/path/to/code',
        # Or '/local/dir'
        base_url        => 'https://www.example.com'
    }
);

my $html = $c->convert($text);

DESCRIPTION

Conflux is a markup language that combines elements of Confluence/JIRA wiki markup and Emacs outline-mode.

The conflux command included with this module is a command line filter that takes in a stream of text in Conflux format and prints it out as HTML.

Unlike some other markup languages, Conflux syntax provides features that are important for technical documents. For example:

Plaintext Table Syntax

You can use Confluence's table syntax instead of having to write HTML tables by hand. This matters a lot if you create and maintain technical documents. (See "Tables" below.)

Automatic Tables of Contents

You can use the toc macro to have a nice table of contents generated for your document. (See "Tables of Contents" below).

Note that syntax highlighting plugins for Vim and Emacs are included in this distribution.

SUPPORTED MARKUP

The subset of Confluence markup that we support is defined as follows:

Headers

The * header format from Emacs outline mode is supported, as in ** Introduction. No other formatting inside the header text is supported. For example, ** Introduction to {{confluence2html}} will not work.

Standard links are supported, e.g., [Link to some other page on this wiki]. This will be rewritten to link to a local file named base_url/link-to-some-other-page-on-this-wiki.html using the base_url argument to the constructor. If no such file exists, this will be a broken link until that file is created. The easiest (but not only) way to do this is to have another file of Confluence markup in the same directory named base_url/link-to-some-other-page-on-this-wiki.txt, and to generate it at the same time.

External links are supported:

[Perl home page|http://www.perl.org]

[http://www.example.org]

Confluence space keys are not supported, since the concept of "spaces" has no meaning in terms of processing a stream of text, which is what this module does. However, a space feature could be added by a more sophisticated application built atop this module.

Macros

Conflux supports a few Confluence-inspired "macros" -- text tags that wrap a section of content and define how that content is processed.

The supported macros are mainly those that are required for a reasonable "publish your writing to HTML" experience. Here's the list:

code
info
tip
note
warning
htmlcomment
table
toc

Other than toc, these macros can only be written as single tags on their own line that delimit blocks of text. For example:

{info}
Have some informative text!
{info}

Unlike old skool Confluence wiki markup, no arguments of the form {info:title=I am the Title} are supported. If you want to add a title your info block for readers, try something like the following:

{info}
*Important Information!*
Your coffee is ready.
{info}

Note that the info, tip, note, warning, and toc macros output as div tags with class names that correspond to the macro name for easy CSS styling. Example output:

<div class="info">
<p>These instructions assume that you have already installed and
correctly configured... For more information, see ... </p>
</div>

This makes it trivial to do things like add background colors for emphasis and the like.

Tables of Contents

Prints a table of contents with links to some or all headers on the page. The following arguments are supported (in addition to none at all): minlevel, maxlevel, exclude -- and they must be supplied in that order. In other words, you must use the toc macro in one of the following ways:

{toc}

Prints a table of contents using all headers on the page.

{toc:minlevel=2}

Prints a table of contents with a minimum header size of 2. The minlevel argument must be an integer between 1 and 6.

{toc:minlevel=2|maxlevel=4}

prints a table of contents with a minimum header size of 2 and a maximum header size of 4. minlevel and maxlevel must be integers between 1 and 6.

{toc:minlevel=2|maxlevel=4|exclude=Further.*}

Prints a table of contents with a minimum header size of 2 and a maximum header size of 4, with any headers matching Further.* (such as "Further Reading") being excluded.

minlevel and maxlevel must be integers between 1 and 6, and exclude is a Perl regular expression literal -- note that the regular expression is not surrounded by quotes.

Lists

Ordered and unordered lists are supported. Example:

+ Apple
+ Banana
+ Cherry

1. Rhubarb
2. Tomato
3. Pomegranate
Line Breaks

The line breaks that appear in the HTML output are those that appear in the text file. There is no support for the Confluence forced line break \\.

Tables

Tables are supported. The only requirement is that you must wrap the table itself in the {table} macro, e.g.:

{table}
| *Name*               | *Rank*   | *Serial Number* |
| Steven Fluffernutter | Sergeant | 314159          |
| Christopher Crunch   | Captain  | 271828          |
| ...                  | ...      | ...             |
| ...                  | ...      | ...             |
{table}

Tip: If you use Emacs, you can use the orgtbl minor mode to navigate, edit, and pretty-print the table contents.

Images

Images are supported, with the following syntax:

!foo.png:450!

This will insert foo.png into the output, at 450 pixels in width. In order for Text::Conflux to know where to find foo.png, you must pass the image_dir variable to the constructor.

BUGS

Many bugs are lurking in this code. Please file issues for any that you find.

AUTHOR

Rich Loveland, mailto:r@rmloveland.com

You can’t perform that action at this time.