NAME
Dancer2::Plugin::MarkdownFilesToHTML
VERSION
version 0.004
SYNOPSIS
No perl code is necessary. Markdown documents can be displayed as HTML inside a Dancer2 app using the Dancer2 `config.yml` file:
plugins:
MarkdownFilesToHTML:
defaults:
header_class: 'elegantshadow scrollspy' # class added to headers
route_root: 'tutorials' # root where routes will get attached
file_root: 'lib/data/markdown_files' # where markdowns file are located
generate_toc: 1 # generate a table of contents
linkable_headers: 1 # generates unique id for headers
template: 'index.tt' # template file to use
layout: 'main.tt' # layout file to use
dialect: 'GitHub' # dialect of markdown file
routes: # list of conversion routes
- dzil_tutorial:
dir: 'Dist-Zilla-for-Beginners' # dir or file property must be set
markdown_extensions:
- md
- mdwn
- another_tutorial:
file: 'intro.md'
template: 'doc.tt' # defaults above can be overridden
generate_toc: 0
linkable_headers: 0See the CONFIGURATION section below for more details on configuration settings.
No configuration file is required, however, and conversion using ordinary Perl code can be accomplshed from with your Dancer2 app like so:
use Dancer2::Plugin::MarkdownFileToHTML;
# convert a single markdown file to HTML
my ($html, $toc) = mdfile_2html('/path/to/file.md',
{ generate_toc => 1, header_class => 'header' });
# convert entire directory of markdown files to HTML
my ($html, $toc) = mdfiles_2html('/dir/with/markdown/files', { generate_toc => 1 });DESCRIPTION
This module converts markdown files into a single HTML string using the Dancer 2 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 all the markdown documents in a directory into an HTML string. Optionally, it can return a second HTML string containing a hierarchical table of contents based on the contents of the markdown documents. These strings can then be inserted into your Dancer2 website. This module extends the Markdent module to perform the conversion.
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
#### Header 4
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.
Conversion keywords can also be called directly from within your Dancer2 app. Note that when called directly and a configuration file is also implemented, most of the default settings (route, template, and layout settings don't apply) still apply but can be overridden.
KEYWORDS
mdfile_2html($file, [ \%options ])
Converts a single markdown file into HTML. An optional hashref can be passed with options as documented in the "General Options" section below.
Example:
my $html = mdile_2html('/path/to/dir/with/makrdown/files');If the $file argument is relative, then it will be appended to the file_root setting in the configuration file. If file_root is not set in the configuration file, lib/data/markdown_files is used.
mdfiles_2html($dir, [ \%options ] )
Attempts to convert all the files present in a directory to markdown and munges them into a single HTML string. By default, the files are processed in alphabetical order.
Example:
my ($html, $toc) = mdiles_2html('/path/to/dir/with/makrdown/files',
{ generate_toc => 1 });If the $dir argument is relative, then it will be appended to the file_root setting in the configuration file. If file_root is not set in the configuration file, lib/data/markdown_files is used.
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.
By default, the method asssumes all files present in a directory are markdown documents and are converted in the order as listed alphabetically in the directory. Hidden files (those beginning with a '.') are automatically excluded. These defaults can be modified. See the "mdfiles_2html Options" section for details.
General Options
OPTIONS
route_root
The root route is the route the individual conversion routes are attached to. For example, if the root route is tutorials, a conversion route named perl will be found at tutorials/perl. If no root route is supplied, / is used.
file_root
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
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
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
Accepts a string which is added to each of the header tags' "class" attribute.
template
The template file to use. index.tt is the default template.
layout
The layout to use. main.tt is the default layout.
dialect
As markdown has no standard, there are many different dialects. By default, the GitHub dialect, as implemented by the Markdent module, is used.
cache
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.
mdfiles_2html Options
All the general options avialable to the mdfile_2html keyword are available plus the following additional options:
markdown_extensions
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.
exclude_files
An array of strings represening the files that should not be converted to HTML.
include_files
An array of strings representing the files that should be converted in the order they are to be converted.
CONFIGURATION
Though the mdfile_2html and mdfile_2html keywords can be passed arguments directly, the configuration file can be used to associate routes with the HTML generatd by the converted markdown files. This makes it very easy to generate new pages on your website. Unless you need to modify the output of the HTML generated by this module in some way, we recommend using the configuration file to generate the pages.
All of the options listed above are supported by the configuration file.
The configuration settings are placed in the config.yml file usually located in the root of your Dancer2 app and begins with:
plugins:
MarkdownFiletoHTML:Follow these two lines with your default settings:
defaults:
header_class: 'my_header classes here'
route_root: 'content'
file_root: '/lib/data/content'
genereate_toc: 1...and so on.
After the defaults, you can list your routes:
routes:
- a_web_page:
dir: 'convert/all/files/in/this/dir/relative/to/file_root'
- another_web_page:
file: '/convert/this/file/with/absolute/path.md'Routes must have either a dir or file property. Relative paths are relative to the file_root default. Consult the #Options section for defaults for each of the options.
The default options can be overridden for each route like so:
routes:
- my_page
file: 'file.md'
toc: 0
header_class: ''The options that apply to directories accept a list of arguments which are create like this:
routes:
- another_page:
dir: 'my_dir_containing_md_file'
include_files
- 'file4.md'
- 'file2.md'
- 'file1.md'
- 'file3.md'Now only files with one of the four names will be get processed in the order listed above.
REQUIRES
SUPPORT
Perldoc
You can find documentation for this module with the perldoc command.
perldoc Dancer2::Plugin::MarkdownFilesToHTMLWebsites
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.
MetaCPAN
A modern, open-source CPAN search engine, useful to view POD in HTML format.
https://metacpan.org/release/Dancer2-Plugin-MarkdownFilesToHTML
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.gitBUGS 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
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.