Adding Kramdown support to process Markdown files

[bexelbie]

This is a proof of concept PR being submitted for feedback. It is not intended to be merged, yet.

Using the kramdown0 processer rich Markdown format is supported for side by side processing with existing AsciiDoc files.

Known Bug: The images used in Markdown files are currently not copied to the output directory. This is because AsciiDoc is currently processed through AsciiDoctor using the data-uri option. There is no analogous option in kramdown. Two options being considered:

a) Get Kramdown to implment a data-uri like option. b) Copy over image files as part of built sites in AsciiBinder when Markdown is detected. This could also result in a new option to allow custom override of the data-uri option.

Known Bug: The additional options (other than data-uri) passed ot AsciiDoctor have not been checked for analougous support in kramdown.

• 'source-highlighter=coderay'
• 'coderay-css=style'
• 'linkcss!'
• 'icons=font'
• 'idprefix='
• 'idseparator=-'
• 'sectanchors'
• 'data-uri' - see above

Specific changes/fixes:

ascii_binder.gemspec:

• add kramdown dependency

lib/ascii_binder/engine.rb:

• add kramdown requirement
• expand topic file definition to include both .adoc and .md files
• when deleting extensions, only remove .adoc - this preserves legacy support for _topic_map.yml entries with no file extension being assumed to be .adoc
  • See: https://github.com/redhataccess/ascii_binder/issues/104
  • This should probably be in a separate PR
  • This needs to have the commented lines delete
• modify output message to reference "topic files" not ".adoc files"
• rename topic_adoc variable that holds the topic file content to topic_content
• add kramdown processing for files ending in '.md'
  • Note: article_title is not supported (see template modifications below)

lib/ascii_binder/tasks/guards.rb:

• watch both .adoc and .md files
  • This is untested

lib/ascii_binder/topic_entity.rb:

• only append .adoc to files that have neither a .adoc or .md extension
  • See related issue: https://github.com/redhataccess/ascii_binder/issues/105
  • This may need to be split into two PRs, one to fix the issue and one for adding .md
• When determining the .html file path, remove either .adoc or .md as needed

templates/_templates/page.html.erb:

• Make display of page-header/article_title optional as it is not supported with Markdown

templates/_topic_map.yml: templates/welcome/index.adoc: templates/welcome/markdown.md:

• Add an example Markdown file and include links between the two files to the template