Asciidoctor :: Discussion

GitHub (or similar) for asciidoc publishing

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

4 messages Options

wimalopaan

GitHub (or similar) for asciidoc publishing

Hi all,

I just realized that github does not support the include:: directive. And I suppose now, that it also doesn't support
asscidoctor-diagram, etc.

1) Is there any perspective to get this working on github

2) Are there alternative free documentation plattforms that fully support asciidoctor / asciidoctor-diagram?

Thanks for any hints,
Wilhelm

abelsromero

Re: GitHub (or similar) for asciidoc publishing

Third-patform support is not really on the Asciidoctor team hands. Collaboration is there, but at the end is up to each platform to decide what features to support.

Said that, GitLab has been more open and does support includes and some diagrams https://docs.gitlab.com/ee/user/asciidoc.html.
On GitHub you will need to resort to preprocessing files (embedding with scripts) and Kroki for diagrams https://kroki.io/.

mojavelinux

Re: GitHub (or similar) for asciidoc publishing

Administrator

I second Abel's recommendation for GitLab. Not only does GitLab support AsciiDoc includes, diagrams, and more, it's also open source. On top of that, support for AsciiDoc on GitLab was contributed by the Asciidoctor community, mostly notably by Guillaume.

If you do need to stick with GitHub for some reason, then what you'll want to do is use GitHub Pages via GitHub Actions. While you won't see support for AsciiDoc includes and diagrams in the repository themselves, you will see them in the files published to GitHub Pages. And it can all stay "in house" so to speak.

But really where you want to be is GitLab.

Best Regards,

-Dan

On Tue, Feb 9, 2021 at 7:27 AM abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Third-patform support is not really on the Asciidoctor team hands. Collaboration is there, but at the end is up to each platform to decide what features to support.

Said that, GitLab has been more open and does support includes and some diagrams https://docs.gitlab.com/ee/user/asciidoc.html.
On GitHub you will need to resort to preprocessing files (embedding with scripts) and Kroki for diagrams https://kroki.io/.

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/GitHub-or-similar-for-asciidoc-publishing-tp8483p8484.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux

msc

Re: GitHub (or similar) for asciidoc publishing

In reply to this post by wimalopaan

> On Feb 9, 2021, at 11:01 PM, wimalopaan [via Asciidoctor :: Discussion] <[hidden email]> wrote:
>
> Hi all,
>
> I just realized that github does not support the include:: directive. And I suppose now, that it also doesn't support
> asscidoctor-diagram, etc.
>
> 1) Is there any perspective to get this working on github
>
> 2) Are there alternative free documentation plattforms that fully support asciidoctor / asciidoctor-diagram?
>

The GitHub Asciidoctor previewer does not support include::. However you can easily run the real Asciidoctor in CI to generate HTML (e.g. via GitHub Actions) which you can deploy to GitHub Pages (the gh-pages branch in your repo).

Regards

-Mark