cryogen-asciidoc

A Clojure library to provide AsciiDoc rendering to the cryogen-core compiler

Usage

Add the latest cryogen-asciidoc dependency to the project.clj of your generated Cryogen blog.

Configuration

You can set AsciidoctorJ Options in Cryogen's config.edn or in the page's metadata under the key :asciidoctor (with either string or keyword keys). Options from the two will be deep-merged (with the page taking precedence when there is a conflict) and passed directly to AsciidoctorJ's .convert method. The most interesting option is :attributes that enables you to set AsciiDoctor attributes via the API.

Examples:

;; config.edn
{:site-title  "AsciiDoctor test"
 ;...
 :asciidoctor {:attributes {"icons" "font"}}}

;; my-ppost.asc
{:title "My awesome post"
 :asciidoctor {:attributes {"abbr-imho" "<abbr title='in my humble opinion'>IMHO</abbr>"}}
 ...}

I would, {abbr-imho}, not ...

Notice that you need to add additional resources to your site for some of the attributes to have the desired effect. For example for :icons: font you likely need to add some parts asciidoctor.css or a variant of it (but it will crash with your Cryogen theme so you might want to extract / create a minimal subset of your own) and FontAwesome.

Extensions

You can register custom Asciidoctor extensions. Currently, only block and inline macros are supported.

For block/inline macros: create a function taking [^BaseProcessor this ^ContentNode parent ^String target attributes] and using the factory methods in BaseProcessor to create a new node. See the AsciidoctorJ extension examples.

By default, you function will be registered as both an inline and block macro so you can invoke it with either mymacro: or mymacro::. If you explicitely only want to allow one of these, you can set the :extension/types metadata to a set of supported types (:inline or/and :block).

You register your extensions in the Cryogen config.edn under :asciidoctor :extensions, which is a map from the macro name to the fully qualified symbol representing the function.

Example - GitHub issue link macro

;; config.edn
{:site-title  "AsciiDoctor test"
 ;...
 :asciidoctor {:extensions {"gh" my.ns/gh}}}

(ns my.ns)
(defn ^{:extension/types #{:inline}} gh
  "Example macro that makes `gh:3[holyjak/myrepo]` into a link to https://github.com/holyjak/myrepo/issues/3"
  [^BaseProcessor this ^ContentNode parent ^String target attributes]
  (let [repo (get attributes "1" "") ; positional attributes get keys such as "1", "2", ...
        href (str "https://github.com/" repo "/issues/" target)
        opts (doto (java.util.HashMap.) ; BEWARE: Must be mutable
               (.putAll {"type" ":link"
                         "target" href}))]
    (.createPhraseNode this parent "anchor" target
                       {}
                       opts)))

Example - abbreviation macro

With the following macro (inspired by asciidoctor/asciidoctor#252), properly register in a similar manner as above, you can write

Now I am talking about abbr:AOP["Aspect-Oriented Programming"], an important topic.

to get

Now I am talking about <abbr title="Aspect-Oriented Programming">AOP</abbr>, ...

The macro:

(defn abbr [^BaseProcessor this ^ContentNode parent ^String target attributes]
  (let [attrs (HashMap. {})
        opts  (HashMap. {"subs" []})]
    (.createPhraseNode
      this parent "quoted"
      (str "<abbr title=\"" (get attributes "1" "N/A") "\">" target "</abbr>")
      attrs opts)))

License

Copyright © 2015 Dmitri Sotnikov [email protected]

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.