Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Slate should support Asciidoc #1

Closed
LightGuard opened this issue Nov 7, 2013 · 13 comments
Closed

Slate should support Asciidoc #1

LightGuard opened this issue Nov 7, 2013 · 13 comments

Comments

@LightGuard
Copy link

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
Copy link
Member

lord commented Nov 7, 2013

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
Copy link
Member

lord commented Nov 19, 2013

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
Copy link
Member

lord commented Nov 22, 2013

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.

@lord lord closed this as completed Nov 22, 2013
@mojavelinux
Copy link

@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
Copy link
Member

lord commented Nov 26, 2013

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

@lord lord reopened this Nov 26, 2013
@mojavelinux
Copy link

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
Copy link

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

@lord
Copy link
Member

lord commented Nov 27, 2013

@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?

@ghost ghost assigned lord Dec 21, 2013
@musashiwasajedi
Copy link

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

@lord
Copy link
Member

lord commented Aug 11, 2014

@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
Copy link

@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
Copy link

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.

Lysholt referenced this issue in e-conomic/slate Nov 26, 2014
@lord lord removed their assignment Dec 5, 2014
costelloej10 pushed a commit to costelloej10/slate that referenced this issue Feb 9, 2015
Add phone and tablet to device_targeting parameters, and note that all v...
makfruit added a commit to makfruit/slate that referenced this issue Mar 13, 2015
ketan added a commit to ketan/api.go.cd that referenced this issue Jun 2, 2015
@lord lord added the wontfix label Jun 20, 2015
@lord
Copy link
Member

lord commented Jun 20, 2015

Maintaining multiple kinds of input formats I think is a little beyond the scope of this project, so I think I'm going to close this. Sorry to anybody who was hoping this would be implemented!

@lord lord closed this as completed Jun 20, 2015
leegeng pushed a commit to leegeng/slate that referenced this issue Jan 29, 2016
스토리 레버리징 1차 관련 API 추가
evilstickman referenced this issue in evilstickman/slate Mar 1, 2017
Ported backand documentation to MD format
evilstickman referenced this issue in evilstickman/slate Mar 1, 2017
Kytanos added a commit to af83/edwig-docs that referenced this issue Apr 26, 2017
adetch pushed a commit to adetch/slate that referenced this issue Nov 9, 2017
andriy-f pushed a commit to andriy-f/slate that referenced this issue Dec 12, 2017
ibc added a commit to versatica/protoo-website that referenced this issue May 29, 2018
biglandy71 pushed a commit to biglandy71/docs that referenced this issue May 30, 2018
atchisson pushed a commit to atchisson/slate that referenced this issue Jul 20, 2018
atchisson pushed a commit to atchisson/slate that referenced this issue Jul 20, 2018
generated from commit 6a44a1c
atchisson pushed a commit to atchisson/slate that referenced this issue Jul 20, 2018
atchisson pushed a commit to atchisson/slate that referenced this issue Jul 20, 2018
99darwin referenced this issue in 99darwin/slate Aug 15, 2018
douglasmuraoka pushed a commit to douglasmuraoka/slate that referenced this issue Nov 7, 2018
ethan-artos referenced this issue in AskCoral/docs-legacy Nov 22, 2018
ethan-artos referenced this issue in AskCoral/docs-legacy Nov 22, 2018
generated from commit c780a02
snmmaurya referenced this issue in coindcx-official/rest-api Apr 13, 2019
aaronbasdeo pushed a commit to aaronbasdeo/slate that referenced this issue Mar 12, 2020
API-99: Setup docker to launch slate locally
aaronbasdeo added a commit to aaronbasdeo/slate that referenced this issue Mar 12, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants