The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dancer2-Plugin-MarkdownFilesToHTML-0.017
River stage zero No dependents
++
/ Dancer2::Plugin::MarkdownFilesToHTML

NAME

Dancer2::Plugin::MarkdownFilesToHTML - Easy conversion of markdown documents to HTML for display in your Dancer2 website

VERSION

version 0.017

SYNOPSIS

Include the plugin in your Dancer2 app:

  use Dancer2::Plugin::MarkdownFilesToHTML;

No other perl code is necessary. Route handlers for displaying the HTML associated with a collection of markdown documents or a single document can be established in the Dancer2 config.yml file:

  plugins:
    MarkdownFilesToHTML:
      defaults:
        header_class: 'elegantshadow scrollspy'  # class added to headers
        prefix: 'tutorials'                      # where routes get attached to
        file_root: 'lib/data/markdown_files'     # location of markdown files
        generate_toc: 1                          # generate a table of contents
        linkable_headers: 1                      # create unique id for headers
        template: 'index.tt'                     # template file to use
        layout: 'main.tt'                        # layout file to use
      routes:                                    # list of conversion routes
        - dzil_tutorial:                         # the route to the page
            resource: 'Dist-Zilla-for-Beginners' # dir with collection of files
            markdown_extensions:
              - md
              - mdwn
        - introduction
            resource: 'intro.md'                 # markdown file to be converted
            template: 'doc.tt'                   # defaults can be overridden
            generate_toc: 0
            linkable_headers: 0

See the "CONFIGURATION" section below for more details on configuration settings.

Markdown file conversion can also be accomplished with the md2html keyword, like so:

  # convert a single markdown file to HTML
  $html = md2html('/path/to/file.md', { header_class => 'header_style' });

  # convert directory of markdown files to HTML and generate table of contents
  ($html, $toc) = md2html('/dir/with/markdown/files', { generate_toc => 1 });

See the "KEYWORDS" section for more informaiton on the md2html keyword.

DESCRIPTION

This module converts markdown files to an HTML string for output to the Dancer2 web app framework. Using the Dancer2 config file, multiple routes can be established in the web app, with each route converting a single markdown document or markdown documents in a directory to HTML. Optionally, it a second HTML string containing a hierarchical table of contents based on the contents of the markdown can also be returned. The md2html keyword is provided if you wish to perform conversions from within an app's module.

This module relies on the Text::Markdown::Hoedown module to execute the markdown conversions which using a fast C module. To further enhance performance, a basic caching mechanism using Storable is employed for each converted markdown file so markdown to HTML conversions are avoided except for new and updated markdown files. See the "MARKDOWN CONVERSION NOTES" for more details on the conversion process.

CONFIGURATION

Use the Dancer2 config.yml file for an easy way to associate routes with HTML generated from converted markdown files. Unless you need to modify the the HTML output by the module in some way, you should use the configuration file method for generating and displaying your HTML.

Edit the config.yml file, usually located in the root of your Dancer2 app, as follows:

  plugins:
    MarkdownFiletoHTML:

Follow these two lines with your default settings:

      defaults:
        header_class: 'my_header classes here'
        prefix: 'content'
        file_root: '/lib/data/content'
        genereate_toc: 1

...and so on.

After the defaults, you can list your routes:

       routes:
         - a_web_page:
           resource: 'convert/all/files/in/this/dir/relative/to/file_root'
         - another_web_page:
           resource: '/convert/this/file/with/absolute/path.md'

Routes must have a resource property that provide a file or directory path to your markdown files. Paths can be absolute or relative. Relative paths are appended to the path in file_root.

Within each route, the default options can be overridden:

         - my_page
           resource: 'file.md'
           generate_toc: 0
           header_class: ''

Consult the "OPTIONS" section for defaults for each of the options.

The options that apply to directories accept a list of arguments, created like this:

          - another_page:
            resource: 'my_dir_containing_md_files'
            include_files:
              - 'file4.md'
              - 'file2.md'
              - 'file1.md'
              - 'file3.md'

Now only the four files listed get processed in the order listed above.

All of the "OPTIONS" listed below are supported by the configuration file.

KEYWORDS

md2html($resource [ \%options ])

Converts a single markdown file or all the files in a directory into HTML. An optional hashref can be passed with options as documented in the "OPTIONS" section below.

Examples:

  ($html, $toc) = md2html('/path/to/file.md',
                  { header_class => 'my_style', generate_toc +> 1 });

  $html) = md2html('/path/to/dir',
                  { header_class => 'my_style', generate_toc +> 1 });

If the $resource argument is relative, it will be appended to the file_root setting in the configuration file. If file_root is not set, lib/data/markdown_files is used.

If a directory of files is convereted, each file can be thought of as a chapter within a single larger document comprised of all the individual files. Ideally, each file will have a single level 1 header tag to serve as the title for the chapter. All files present in a directory are markdown documents. Hidden files (those beginning with a '.') are automatically excluded. These defaults can be modified.

OPTIONS

"General Options" apply to both file and directory resources. See the "Directory Options" section for options that let you control how files in a directory are processed and selected.

General Options

prefix => $route

The prefix is the route the individual conversion routes are attached to. For example, if the prefix is tutorials, a conversion route named perl will be found at tutorials/perl. If no prefix is supplied, / is used.

file_root => $path

The root directory where markdown files can be found. Defaults to the lib/data/markdown_files directory within the Dancer2 web app. Directories and files supplied by each route will be relative to this path if they are relative. If directory or file path is absolute, this value is ignored.

generate_toc => $bool

A boolean value that defaults to false. If true, the function will return a second string containing a table of contents with anchor tags linking to the associated headers in the content. This setting effectively sets the linkable_headers option to true (see below).

linkable_headers => $bool

A boolean value that defaults to false. If true, a unique id is inserted into the header HTML tags so they can be linked to. Linkable headers are also generated if the toc generate_toc option is true.

header_class => $classes

Accepts a string which is added to each of the header tags' "class" attribute.

template => $template_file

The template file to use relative to directory where the app's views are store. index.tt is the default template.

layout => $layout_file

The layout file to use relative to the app's layout directory main.tt is the default layout.

cache => $bool

Stores generated html in files. If the timestamp of the cached file indicates the original file been updated, a new version of page will be generated. The cache defaults to true and there is no good reason to turn this off except to troubleshoot problems with the cache.

Directory Options

include_files => [ $file1, $file2, ... ]

An array of strings representing the files that should be converted in the order they are to be converted.

By default, the files are processed in alphabetical order. Though alphabetical ordering can be overridden manually using the include_files option, it's easier to use a naming convention for your files that will places them in the desired order:

  tutorial01.md
  tutorial02.md
  tutorial03.md
  etc.

exclude_files => [ $file1, $file2, ... ]

An array of strings represening the files that should not be converted to HTML.

markdown_extensions => [ $ext1, $ext2, ... ]

An array of strings representing the extensions that should be used to determine which files contain the markdown documents. This option is valid only with the mdfiles_2html) keyword. Only files with the listed extension will be converted.

MARKDOWN CONVERSION NOTES

The module aims to support the dialect of markdown as implemented by GitHub with strikethroughs (~~strike~~) and "fenced" code (```fenced code```). This module may make the dialect options configurable in the future.

The module will add a "single-line" class to single lines of code to facility additional styling.

The module is particarly well-suited for markdown that follows a classic outline structure with markdown headers, like so:

  # Title of Document

  ## Header 2

  ### Header 3

  And so on...

Each header is converted to a <hX\> html tag where X is the level corresponding header level in the markdown file. If present, the headers can be used to generate the table of contents and associated anchor tags for linking to each of the sections within the document. If headers are not present in the markdown file, a useful table of contents cannot be generated.

REQUIRES

SUPPORT

Perldoc

You can find documentation for this module with the perldoc command.

  perldoc Dancer2::Plugin::MarkdownFilesToHTML

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Source Code

The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)

https://github.com/sdondley/Dancer2-Plugin-MarkdownFilesToHTML

  git clone git://github.com/sdondley/Dancer2-Plugin-MarkdownFilesToHTML.git

BUGS AND LIMITATIONS

You can make new bug reports, and view existing ones, through the web interface at https://github.com/sdondley/Dancer2-Plugin-MarkdownFilesToHTML/issues.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

SEE ALSO

Dancer2

Text::Markup::Hoedown

AUTHOR

Steve Dondley <s@dondley.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Steve Dondley.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.