-
Notifications
You must be signed in to change notification settings - Fork 803
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
Document the constraints of hosting AsciiDoc content on GitHub #939
Comments
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). |
Thanks for the explanation and appreciate the promptness |
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.
The text was updated successfully, but these errors were encountered: