@Sherspock

Is this supported somehow without making use of a process-and-commit pipeline, whether by workaround or not?

Not in GitHub, but they do work in Gitlab. But with GH-Actions the procres is made really easy.

I've also tried using the AsciiDoc chrome plugin in Brave with no luck properly rendering adocs with include directives in them on GitHub either.

Just guessing, but if you are using something like include::my-part.adoc[] I doubt the plugin is able get the path. Overall, I'd recomend not to try to get a 100% accurate local preview or repository UI preview, complex doc builds just will require doing a full conversion.
Said that, on the bright side, intellij plugin offers the best experience so far in local, with a decent preview, autocomplete and refactor features.

Does this work in GitLab? github/markup#1095 isn't stagnant, but I didn't see anything that looked especially promising at a glance.

Yes, not a rant, just facts. It's true that GitLab team has been more open to imprevements that GitHub, work with the later is slower.

I spent a little chunk of time trying to find your workaround in both the project you
mentioned and the project it was absorbed into. Naturally I had to backtrack a little
with SUSE. I couldn't actually find a single instance in either of an include rendering > properly in GitHub.

As far as I know including files in ASCIIDoc documents as well as resolving attributes is disabled for security reasons on GitHub.
However, it looks like a simple include statement at least results in a clickable link to the included document in the meantime, so the workaround I posted above is no longer needed (see https://github.com/SUSE/doc-caasp/blob/master/adoc/book_admin.adoc for an example).

Does this work in GitLab?

https://about.gitlab.com/releases/2019/06/22/gitlab-12-0-released/#support-for-asciidoc-include-directive
It at least works in an on premise Gitlab installation I am using (including resolving of attributes), haven't tested gitlab.com, though.

@abelsromero
Thank you much! Without understanding it better or having some clear examples of how it might work in my specific context, the idea of allowing an action to commit changes makes me nervous. I appreciate the GitLab and plugin tip!

@fsundermeyer
Ah, thank you! It's clear to me now I didn't understand what that workaround was for.

Looks like a self-hosted instance of GitLab isn't necessary to make this work. I have confirmed that includes and attributes appear to work just fine on GitLab. At least in a simple test case including text and an attribute from a single document into another with a reference to that attribute.

@Sherspock

Thank you much! Without understanding it better or having some clear examples of how it might work in my specific context, the idea of allowing an action to commit changes makes me nervous. I appreciate the GitLab and plugin tip!

The publicaton in fact is trivial with https://github.com/JamesIves/github-pages-deploy-action. Here is an example of a GH-Action that publishes and Antora/Asciidoctor site on GH-Pages when a change on "main" branch is done, docs are in a folder called "docs" alongside the code. The tricky part is using upload-artifact and download-artifact to share the resulted converted docs in HTML between conversion and push steps.
The only thing to adapt is the "Generate site using antora site action", the rest is always the same.

To know more just drop by the asciidoctor gitter channels or the forum.

name: Build & publish docs
on:
  push:
    branches:
      - main

env:
  SITE_DIR: 'site'

jobs:
  build_site:
    name: "Build site with Antora"
    runs-on: [ubuntu-latest]
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: "Generate site using antora site action"
        uses: kameshsampath/antora-site-action@master
        with:
          antora_playbook: antora-playbook.yml
      - name: "Upload generated site"
        uses: actions/[email protected]
        with:
          name: site
          path: "${{ github.workspace }}/build/${{ env.SITE_DIR }}"
  deploy_site:
    runs-on: [ubuntu-latest]
    needs: [build_site]
    name: "Deploy GitHub Pages"
    steps:
      - name: Setup Node.js for use with actions
        uses: actions/[email protected]
        with:
          version: '14'
      - name: Checkout
        uses: actions/checkout@v2
      - name: Download generated site
        uses: actions/download-artifact@v1
        with:
          name: site
          path: "${{ github.workspace }}/${{ env.SITE_DIR }}"
      - name: Deploy to GitHub Pages
        uses: JamesIves/[email protected]
        with:
          GITHUB_TOKEN: "${{ github.token}}"
          FOLDER: "${{ env.SITE_DIR }}"
          BRANCH: 'gh-pages'
          COMMIT_MESSAGE: "[CI] Publish Documentation for ${{ github.sha }}"
          CLEAN: true

As we work on revamping the docs site for Asciidoctor, I would love to see a section dedicated to succeeding with AsciiDoc on GitHub. There are certainly idiosyncrasies to understand and having a docs page on the topic will certainly help people who host their AsciiDoc files there. Perhaps consider submitting this to the new docs for Asciidoctor (which will live in the main asciidoctor repository).

My only objection is the term "GitHub Flavored AsciiDoc". There is no such thing. Please don't use this term as it suggests fragmentation that's simply not there (like there is with Markdown). There is only one AsciiDoc. The software GitHub uses to process it is the same software that's used throughout the ecosystem (Asciidoctor). What differs is how the rendered HTML is displayed. GitHub applies their own stylesheet to it, one that we have little control over. There is a somewhat unspoken API with the stylesheet in AsciiDoc that becomes visible when a different stylesheet is applied. I think those differences are certainly worth noting. GitHub also disables includes, but that is another matter.

(If any term applies here, it would be GitHub Limited AsciiDoc. But I'm concerned that would come across as unnecessarily critical.)

In order for [images] to be rendered inline, you must provide an absolute path to the :imagesdir: directive.

This is not a true assertion. Relative image paths do work. If the document is nested in a different structure than the images, you may need to use a different value compared to your publishing environment. But relative paths work even in this scenario.

what about math? math does not render for me on github.

Thanks for the tip on how to get admonitions with icons working on GitHub. Take a look at my AsciiDoc README Template.

@mojavelinux thanks for pointing out that all includes are disabled in GitHub. Furthermore, the most important messages was, that there is no fragmentation and no GitHub Flavored Asciidoc (GFA).

what about math? math does not render for me on github.

It's true that math (i.e., STEM) does not render on GitHub. Though there are workarounds we could still explore, like using their image service to generate an SVG (e.g., https://render.githubusercontent.com/render/math?math=\displaystyle \text{b} = V D) But just because GitHub won't render something doesn't make it not AsciiDoc. It just means GitHub is not providing a full fidelity experience. And there's literally nothing we can do about it*. We have offered to help. But at the end of the day, it's their platform and their choice. And they simply refuse to implement certain display features, despite countless pleas from the community.

Where you do see these display features implemented is on GitLab. I think, in many ways, they are leading the way on what it means to support AsciiDoc properly in a repository browser, and hopefully others will follow.

* Perhaps the AsciiDoc WG can play an arbitration role. We'll have to see.

@JoeArauzo Nice!

Thanks for this! Any tips on rendering mermaid diagrams in asciidoc READMEs?

Thanks for this! Any tips on rendering mermaid diagrams in asciidoc READMEs?

I see mention of mermaid diagrams at https://asciidoctor.org/docs/asciidoctor-diagram/.

:toc:
:toc-placement!:

Here is my preamble paragraph, but I could really place the TOC anywhere! Lorem ipsum foo bar baz.

toc::[]

It's nice. Thank you!

Does GitHub exposeb any other custom attributes except env-github ?
Or maybe there is a way to detect current repo name.

It could be extremely usuful for PR s.

@dcode thanks for putting this out there, it's a great demo of what Asciidoc can do in GitHub. I did notice that all of your links are broken, for example the first link should be link:http://asciidoctor.org/[Asciidoctor] not link::http://asciidoctor.org/[Asciidoctor]. The issue is that you are using link:: instead of the normal link: macro to start your links.

It looks like it might not be possible to have inline rendered images in an AsciiDoc file in a private repo.

I think it assumes the <img src= value used to render the image will be base url from imagesdir + image file name from image reference

But in a private repo, there is a token on the end of the URL for any raw file.

Anyone else notice that sidebars don't render well on GH? I tried using it here https://github.com/b-layer/musecnav#popup (it starts with the text "Numerical Selection in the Popup"). No visual delineation...looks terrible. Looks fine locally.

@b-layer There's not much tha can be done. This is GitHub-Flavored Asciidoc, not all features are allowed and there are some style modifications. Using GH preview is nice for simple things, but not something to consider for a professional result.

@abelsromero Yes, thanks, I'm aware of all that but I hadn't seen any mention of this particular failing before (e.g. in the gist we're commenting on) and was wondering if perhaps I'd missed something, if there is any known workaround and if no to both of those at least to note it for any future readers wondering the same thing.

I've tested using the .ad file name extension several times, already. It simply does not work!

How to use asciidoc in the issue?

@theAkito You must use either .asciidoc, .adoc, or .asc, per https://github.com/github/markup/blob/master/README.md#markups.

nice doc!
it is a pity that Github does not have the same level of support for asciidoc as gitlab
in particular supporting math

Nice if statement helps me a lot. thank you.

I just created a README.ad but it is not rendered at all...
Edit: Turns out .ad is not recognized, so use .adoc.

@dcode Please correct this gist by replacing .ad with .asc!

Leaving the list of official file extensions here because it always takes me some time to find 👉 https://github.com/github/markup/blob/master/README.md#markups (.asciidoc, .adoc, .asc)

file extension updated. It did used to be .ad. I never intended this gist to be an authoritative documentation source, but I'm glad it's helped so many people! Sorry it took so long to get the file extension edited.

Fixed the links, as well.

About

:toc:
:toc-placement!:

Here is my preamble paragraph, but I could really place the TOC anywhere! Lorem ipsum foo bar baz.

toc::[]

This is deprecated.
If you want to position toc::[] anywhere, now use:

:toc: macro

Here is my preamble paragraph, but I could really place the TOC anywhere! Lorem ipsum foo bar baz.

toc::[]

If you want to position it after a preamble, use this:

:toc: preamble

Here is my preamble.
The toc will be inserted after the ''' (this insert a line) and before the first section.
No need to use the macro toc::[] anymore.

'''

== First section

source