Quick step-by-step guide

  1. Precondition, get a user account on github (to follow along with this demo, start at https://github.com, there is a free option)

  2. Browse to https://github.com/asciidoctor/jekyll-asciidoc-quickstart

  3. Click the green 'Use this template' button

  4. Pick 'create a new repository' on the drop-down page that appears

  5. Enter your Github username or your organization name under the dropdown in the 'Owner' column

  6. Enter a repository name for your documentation repository

  7. Enter an optional description for the repo

  8. Choose the radio button for 'public' unless you want to make the repo private

  9. Click the green 'Create repository from template'

  10. Your new template-clone repository opens to the README.adoc

  11. Click on 'Settings' on top toolbar

  12. Click on 'Pages' on left navbar

  13. Under the Source heading, select the 'GitHub Actions' option

  14. Notice that 'Jekyll' is pre-selected under 'use a suggested workflow…​'

  15. Click 'configure' to create the prepopulated jekyll.yml config file

  16. Click the green 'Commit changes…​'

  17. Click Actions on top toobar

  18. Watch the build/deploy workflow (for details, click on 'build' or 'deploy')

  19. Scroll back to the top of 'Github Pages' where you will see a 'Visit site' button. Click it.

  20. The Quickstart page appears, hosted in the repo you created.

  21. If you open index.adoc for edits, add a sentence somewhere and commit the change, the auto-republication workflow will begin.

  22. Click on 'actions' on the top toolbar to track the process.

  23. When the process finishes, revisit the site and you should see the changes you made.

  24. To create 'spaces' (in Confluence terminology), create a 'doc' directory at the same level as the index.adoc

  25. To create 'pages', add a newfile.adoc file in the 'doc' directory

  26. Edit index.adoc to include a cross-reference to the new file: xref:doc/newfile.adoc

  27. When the site auto-publish workflow completes, the new link in index.adoc will take you to the new 'page' in the 'doc' space.