Project: trac-wiki - The Ruby Toolbox

= TracWiki =

TracWiki is a TracWiki-to-HTML converter for Trac wiki, http://trac.edgewall.org/wiki/WikiFormatting.

Project page on github:

* http://github.com/vitstradal/trac-wiki

== INSTALLATION ==

    gem install trac-wiki

== SYNOPSIS ==

    require 'trac-wiki'
    html = TracWiki.render('== TracWiki text ==')
    # or
    html = TracWiki.render('== TracWiki text ==', options)


    parser = TracWiki.parser(options)

    parser.to_html(text1)
    parser.to_html(text2)


== Options ==

* `allowed_schemes`
   Allowed url schemes
   Examples: http https ftp ftps

* `base`
   base URL (or URI), for link and images

* `no_escape`
    Disable url escaping for local links
    Escaping: [[/Test]] --> %2FTest
    No escaping: [[/Test]] --> Test


* `no_link`
    Disable url escaping for local links
    `[[whatwerver]]` stays `[[whatwerver]]`

* `math`
    math syntax extension:
    $e^x$ for inline math,
    $$ e^x $$ for display math

* `allow_html`
    allow some <b> <form> <html>
    html will be sanitized

* `edit_heading`
    add '<a class='editheading' href="?edit=N>edit</a>'
    to each heading

* `merge`
    understand merge tags  (see diff3(1))
    >>>>>>> mine
    ||||||| orig
    =======
    <<<<<<< yours
    convert to <div class="merge merge-mine">mine</div>

* `id_from_heading`
    every heading had id, generated from heading text

* `id_translit`
    when `id_from_heading`, non ascii char are transliterated to ascii (Těžiště -> Teziste)

* `template_handler`
    template_handler(macroname) -> template_text
    when macros enabled and {{myCoolMacro}} ocured,
    result fo `template_handler('myCoolMacro') inserted

* `macros`
   enable macros|templates (in mediawiki style).
   macros are in form `{{macro_name | arg1 | arg2 }}`

* `macro_commands`
    like template but more powerfull
    do no use.

== Other parser attributes and functions ==

* `parser.headings`
    structure where headings are stored (after parse)
    list of hasheses with `level` and `title`, `sline`
    [ { leven: 1, # <h1>
        sline: 3, # line where head starts
        eline: 4, # line before next heading starts
        aname: 'anchor-to-this-heading',
        title: 'heading title'
      },
      ...
    ]

* `parser.was_math?`
  if math (inline or dispayed) was parsed.

* `parser.make_toc_html`
  create html toc from previously parsed text

* `parser.add_macro_command(name, &block)`

* `parser.env.(env|at(key))`
   access to env values after parse

== Macros ==

* `{{template}}`
* `{{$variable}}`
   * can be set by  {{!set variable|value}}
   * `$1`, `$2` parameters send to template {{template ONE|TWO}}
   * parameters send to template can be named {{template ahoj=test|hi=west}}
   * `$0` all parameters (without named)
   * `$00` all parameters (with named)

* `{{unknown_macro par1}}` is expanded  to `{{unkmacro unknown_macro|par1}}`,
   you have to specify `uknmacro` macro. If not, error strig
   `UNKNOWN-MACRO(unkmacro)`
   is generated.

* `{{!command}}`

== BUGS ==

If you found a bug, please report it at the TracWiki project's tracker
on GitHub:

http://github.com/vitstradal/trac-wiki/issues

== AUTHORS ==

* Vitas Stradal

== LICENSE ==


GPL