asciidoc static site on github pages

Jun 15, 2021

I wrote a python reference doc for our intro Comp Sci students, and I wanted to host the repo here on github, but also host the static website, which is written in asciidoc.

This post shows the steps needed (one way) to turn asciidoc files into a static website as part of your github pages (a separate repo that gets published to a sub-url of your github pages).

docs I followed

And the final result is this python reference doc.

the setup

make a new github repo
clone it
add some adoc files
note: I think Manoel’s github action needs a README.adoc file, so make sure you at least have that
git commit/push the adoc files back to github
following the github workflow doc:
- click on “Actions” (on main repo page)
- click “Set up this workflow” for the simple “Blank” workflow file
- “Start commit”
- Commit directly to the “main” branch
- “Propose new file”
now back in your repo, run a “git pull” and you should see a new .github/workflow/blank.yml file
edit the blank.yml file to add Manoel’s asciidoctor-ghpages addition: ``` # Includes the AsciiDoctor GitHub Pages Action to convert adoc files to html and publish to gh-pages branch
- name: asciidoctor-ghpages uses: manoelcampos/asciidoctor-ghpages-action@v2 with: asciidoctor_params: –attribute=nofooter ```
git commit/push that back to github
now back on your repo’s github.com page:
- click “Settings”
- go to/find the GitHub Pages tab (just above the Danger Zone)
- under Source, select the gh-pages branch
- then click Save

I think at this point you need one more git push to activate and build the whole thing, so make another edit in one of your adoc files and git commit/push the change.

After a git push, if you go to your github repo Actions tab, you should now see the running workflow, and hopefully a green check mark. If it’s not green, you can click on the workflow to see any debugging info.

If everything worked your site should be deployed to https://USERNAME.github.io/REPONAME