search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 807 forks source link

Document the constraints of hosting AsciiDoc content on GitHub #939

Closed ShahBinoy closed 4 years ago

ShahBinoy commented 4 years ago

We want to keep all our project documentation on Github only. It seems that github.com flavored asciidoc has some limitations

Can we provide a page as a adoc file on github that exemplifies such limitation.

for example the callouts in code samples never show up as icons I added :icons: font in the document header and still it does not show up.

Is there a page or link where I can lookup the limitations or incompatibilities.

mojavelinux commented 4 years ago

I want to point out that there is no such thing as GitHub-flavored AsciiDoc. There's only one definition of AsciiDoc, and it's what Asciidoctor implements.

It's true that certain HTML elements produced from converting an AsciiDoc document are limited to specific security modes and/or rely on assistance from CSS. And GitHub doesn't provide all the necessary CSS. Though even that CSS is still just a recommendation, not a requirement. It doesn't change how the AsciiDoc itself is parsed or interpreted.

On GitHub, Asciidoctor runs in secure mode, the restrictions of which can be foun here: https://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely

Although a bit outdated, you might find this blog post helpful: https://asciidoctor.org/news/2014/02/04/github-asciidoctor-0.1.4-upgrade-5-things-to-know/

And there's this tip sheet (though I denounce the name GFA): https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74

I also maintain a page that reveals runtime information about the version of Asciidoctor running on GitHub: https://github.com/opendevise/asciidoc-samples/edit/master/runtime.adoc

As for the icons, you're likely looking for this section of the docs: https://asciidoctor.org/docs/user-manual/#unicode-admonition-icons

At the end of the day, the output of an AsciiDoc on GitHub will always just be a preview. If you want the full power of what Asciidoctor offers, you need to run the converter and publish the output you produce yourself (such as using GitHub Pages, Netlify, etc).

ShahBinoy commented 4 years ago

Thanks for the explanation and appreciate the promptness