Slate should support Asciidoc

[LightGuard]

As slate is a Ruby application, it should be pretty trivial to support AsciiDoc via AsciiDoctor github.com/asciidoctor/asciidoctor. I'm sure @mojavelinux would be able to lend a hand.

[lord]

Thanks for the suggestion! As I understand it, the static site generator we use, Middleman, supports AsciiDoc out of the box. I can look into more details like compatibility with our syntax highlighting and table of contents when I get back from vacation.

[lord]

Looked into it, should be easy enough. The only thing that's broken with AsciiDoc is our CSS styles. I'll adapt them to be AsciiDoc compatible some time this week or next.

[lord]

Sorry, but I'm going to have to mark this as a wontfix. AsciiDoc adds way too many extra HTML elements and div wrappers for it to be easily integrated with Slate.

That said, if anybody else would like to do this, I would be more than happy to accept a pull request.

[mojavelinux]

@lord I far better approach is to customize the AsciiDoc backend to conform to your styles. That way, you don't have to change anything, but you get the power of AsciiDoc.

We already have lots of backends, so creating a new one goes pretty quickly.

https://github.com/asciidoctor/asciidoctor-backends

The reasons the default HTML output is rather verbose is because AsciiDoc supports most of the formal structure elements allowed by DocBook. There's nothing preventing you from creating a backend that produces HTML as simple as Markdown.

[lord]

@mojavelinux ah, I didn't see that. I'll take another look.

[mojavelinux]

I'd be glad to integrate the backend into asciidoctor-backends. You can call it slate perhaps. If you fork the repo and get it started, I'd be happy to help move it along.

It would also give us to opportunity to find patterns that could simplify the markup source you use while adding more semantics to it.

[mojavelinux]

Of course, if you want to have the backend in slate itself, that works to. Either way I'd be happy to help.

[lord]

@mojavelinux okay, so if we put the template files in asciidoctor-backends, the tasks for a user who wants to use Asciidoc would be:

• Add asciidoctor to gemfile, run bundle.
• Clone asciidoctor-backends to their Slate directory.
• Add a reference to asciidoctor-backends/erb/slate in their config.rb.
• Add a index.html.adoc file.
• Run the server.

Does that sound right? asciidoctor-backends is not included with asciidoctor, right?

[musashiwasajedi]

Just curious, did this ever happen? Would love to hook up slate to our asciidocs. :)

[lord]

@musashiwasajedi not yet! I'm still figuring out how the workflow would work with syntax highlighting and choosing the asciidoc template. Definitely on the radar though!

[mojavelinux]

@lord The best solution is to simply maintain the templates for Asciidoctor in the slate repository. After all, you are customizing the HTML to fit your framework, so the user really doesn't need to know about them.

As of Asciidoctor 1.5.0 there are many options for customizing the HTML. The quickest way is to use templates. These templates can be loaded from file or they can be loaded from a string (see this discussion post for details on the latter: http://discuss.asciidoctor.org/Backends-as-Stream-td1595.html).

You also have to option of supplying a Ruby-based converter that replaces the built-in HTML5 converter. You can just copy the existing HTML5 converter and start hacking on it. You can strip away and conversions you don't need in the context of slate. It's up to you what you support and how you do it.

To register your own converter impl, just pass it to the Asciidoctor API:

require 'asciidoctor'
require 'asciidoctor/converter/html5'

class SlateHtml5Converter < Asciidoctor::Converter::Html5Converter
  def paragraph node
    %(<p>#{node.content}</p>)
  end
end

source = 'sample text'
output = Asciidoctor.convert source,
    header_footer: true,
    safe: :safe,
    converter: SlateHtml5Converter
puts output

I hope that helps!

[mojavelinux]

The whole idea of Asciidoctor is to be able to customize the output, so feel free to massage it to produce the HTML that works for you.