html-pipeline-asciidoc_filter's Introduction

AsciiDoc filter for html-pipeline

html-pipeline-asciidoc_filter is an AsciiDoc processing filter for html-pipeline based on Asciidoctor.

This filter is used to render AsciiDoc files in GitHub repositories, among other uses. Keep in mind that an HTML sanitization filter is run after this filter, so not all elements in the AsciiDoc document render correctly. We need to improve the output generated by this filter to get better results.

Example Usage

require 'html/pipeline'
require 'html/pipeline/asciidoc_filter'

filters = [
  HTML::Pipeline::AsciiDocFilter,
  HTML::Pipeline::SanitizationFilter,
  HTML::Pipeline::ImageMaxWidthFilter,
  HTML::Pipeline::EmojiFilter,
  HTML::Pipeline::MentionFilter,
  HTML::Pipeline::AutolinkFilter,
  HTML::Pipeline::TableOfContentsFilter,
  HTML::Pipeline::SyntaxHighlightFilter
]

context = {
  :asset_root => 'https://github.global.ssl.fastly.net/images/icons/emoji'
}

pipeline = HTML::Pipeline.new filters, context
pipeline.setup_instrumentation

input = <<-EOS
= Sample Document
Author Name

Preamble paragraph.

== Sample Section

Section content.

.GitHub usernames
- @jch
- @rtomayko
- @mojavelinux

[source,ruby]
--
require 'asciidoctor'

puts Asciidoctor.render('This filter brought to you by http://asciidoctor.org[Asciidoctor].')
--

:shipit:
EOS

puts pipeline.call(input)[:output]

Note about dependencies

You’ll need the following two dependencies which aren’t declared by html-pipeline or this filter.

gem 'activesupport', '>= 2'
gem 'github-linguist', '~> 1.2.6'

TODO

remove <p> from text-only list items by defining custom block_paragraph template
preserve ToC (likely through subsequent filter)
retain checklist items in list (perhaps using text-based checkmarks)
enable font-based icons