Guides on GitHub are not easy to follow

[robertmcnees]

Due to security concerns, Asciidoc include functionality is not rendered on GitHub. The reasons are detailed in this GitHub issue. Because the Spring getting started guides make heavy use of include functionality, the reader will see empty blocks of content if they are consuming the README.md directly from the GitHub page.

For example, the user may see this when visiting the GitHub page:

But this when visiting the same guide on spring.io:

[robertmcnees]

A possible solution is to use Asciidoc Reducer with the allow-uri-read option. The GitHub Action could run each time the README.adoc file is changed. The action may look something like:

jobs:
  build:
    runs-on: ubuntu-latest
        # checkout code

      - name: Install Asciidoctor Reducer
        run: sudo gem install asciidoctor-reducer
      - name: Reduce README
        run: asciidoctor-reducer -a allow-uri-read -o README-reduced.adoc README.adoc

        # commit and push README-reduced.adoc

The output of this would be a new README-reduced.adoc file that would show the included content from README.adoc.

This would require coordination with guides renderer. The guides renderer would need to look for a file other than README.adoc to generate content, or GitHub would need to look for a file other than README.adoc to display by default.