/ 
Ado-0.935
River stage zero No dependents
/ Ado::Plugin::MarkdownRenderer

NAME

Ado::Plugin::MarkDownRenderer - Render markdown to HTML

SYNOPSIS

#1. Use one or more markup parsers
plugins => [
  #...
  #use default configuration
  'markdown_renderer',

  #Create your own Text::Trac based wiki
  {name => 'markdown_renderer', config => {
    md_renderer =>'Text::Trac',
    md_options => {
      trac_url      => '/wiki',
      disable_links => [ qw( changeset ticket ) ],
    },
    md_method => 'parse',
    md_helper =>'trac_to_html'
  }},
  #...
],

#2. Describe your routes
routes     => [
      #markdown_renderer route is already configured
      #in etc/plugins/markdown_renderer.conf.

      #Your own great enterprise wiki
      {route => '/wiki/*md_file', via => ['GET'],
        to => 'wiki#show',},
      #...
      ],

#3. Write your controller
package Ado::Control::Wiki;
use Mojo::Base 'Ado::Control';
#...

DESCRIPTION

Ado::Plugin::MarkdownRenderer is a markdown renderer (маани, маани!)

You only need to create a controller for your enterprise wiki and use the "md_to_html" helper provided by this plugin. See Ado::Control::Doc for an example.

You may use this plugin to load and use other markup languages parsers and converters to HTML.

The code of this plugin is a good example for learning to build new plugins, you're welcome to fork it.

OPTIONS

The following options can be set in etc/plugins/markdown_renderer.$mode.conf or etc/ado.conf. You can find default options in etc/plugins/markdown_renderer.conf. md_ prefix is short for "markup document" or "markdown".

md_renderer

md_renderer => 'Text::MultiMarkdown',

The class to load. This option exists because the user may want to use Text::Markdown or Text::Markup instead.

md_method

md_method => 'markdown',

Method that will be used internally to produce the $HTML. Can also be a code reference. First parameter is the md_renderer instance and the second is the markdown text.

md_options

md_options => {
    use_wikilinks => 1,
    base_url      => '/docs',
},

These options will be passed to the md_renderer constructor. They are specific for each markup parser so look at it's documentation.

md_helper

md_helper => 'md_to_html',

Helper name. You may want to change this if you want to have different helpers for different markup converters, configurations, applications etc. in the same ado instance. Default helper name is "md_to_html".

md_root

md_root         => app->home->rel_dir('public/doc'),

Directory where the raw files reside.

md_articles_root

md_articles_root         => app->home->rel_dir('public/articles'),

Directory used by Ado::Control::Articles where the raw markdown files reside and where the static HTML files are generated.

md_file_sufixes

md_file_sufixes => ['.md'],

File-suffixes supported by your renderer.

md_reuse_produced_html

md_reuse_produced_html => 1,

Do not convert files on every request but reuse already produced html files.

HELPERS

Ado::Plugin::MarkdownRenderer exports the following helpers for use in Ado::Control methods and templates.

markdown

Accepts markdown text and options. Returns HTML. Accepts the same parameters as "markdown" in Text::MulltiMarkdown

#in a controller
$c->render(text=>$c->markdown($text));

#in a template
%==markdown($text)

md_to_html

Given a Markdown string returns <article>$html</article> produced by the converter - Text::MultiMarkdown by default. You may want to use your own helper name. See "md_helper".

#Markdown from $MOJO_HOME/public/doc/bg/intro.md
#http://example.com/doc/bg/intro.md
my $html = $c->md_to_html();

#Markdown from arbitrary file
my $html_string = $c->md_to_html($some_filepath);

% #in a template
<%= md_to_html();%>
% #<article>$html</article>

METHODS

Ado::Plugin::MarkdownRenderer inherits all methods from Ado::Plugin and implements the following new ones.

register

my $plugin = $app->plugin('markdown_renderer' => $OPTIONS);

Register renderer and helper in Ado. Return $self.

SPONSORS

The original author

Become a sponsor and help make Ado the ERP for the enterprise!

SEE ALSO

Ado::Control::Doc, Ado::Control::Articles, Text::MultiMarkdown, http://fletcherpenney.net/multimarkdown/, MultiMarkdown Guide Ado::Plugin, Ado::Manual.

AUTHOR

Красимир Беров (Krasimir Berov)

COPYRIGHT AND LICENSE

Copyright 2013-2014 Красимир Беров (Krasimir Berov).

This program is free software, you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License v3 (LGPL-3.0). You may copy, distribute and modify the software provided that modifications are open source. However, software that includes the license may release under a different license.

See http://opensource.org/licenses/lgpl-3.0.html for more information.