The Jekyll AsciiDoc Quickstart project is a leg-up in starting your own website hosted on GitHub and GitHub Pages with content based in AsciiDoc. This project combines the power of AsciiDoc with a beautiful CSS framework and blog-ready template on top of GitHub’s existing publishing infrastructure.
This project provides a GitHub Action workflow that republishes your website when changes are pushed to the repository.
The workflow watches for commits on the master or main branch, automatically runs the Jekyll build, and pushes the generated content to the gh-pages branch.
-
Click the Fork button in the upper right corner of GitHub to create your own copy of this repository.
-
After the fork is completed and you’re redirected to your own repository copy:
-
Access the Settings tab, then the Pages menu on the left.
-
In the source field, select the
gh-pagesbranch to be the source of the website files (this branch is where the Jekyll build will place the generated files). -
Finally, click the Save button and return to your respository home.
-
After every push, the GitHub Action workflow is automatically started to build and publish your website. That takes a while. You can look for ✅ at the top of your repository home page.
If you can load the URL at https://github-username.github.io/name-of-repository, then you have successfully completed the basic configuration.
Start writing blog posts and enjoy the AsciiDoc difference, regardless of what device you choose: computer, tablet, or mobile.
You must install some software to build and serve your website locally. The requirements on the Jekyll Installation page describe how to install both Ruby and RubyGems.
If you would like to work offline first, consider checking your Gemfile for the versions of your gem sources.
If the jekyll serve command fails, it likely means you don’t have the necessary gems installed
You can check whether the jekyll gem is installed locally by running gem list --local | grep "jekyll".
GitHub Pages does not (yet) whitelist the jekyll-asciidoc plug-in, so you can not write .adoc posts and have them instantly published like Markdown posts do.
However, the only additional thing we need is the publish.yml workflow which is already configured in this repository.
You don’t have to change it, unless you want to perform some customization in the build/publish process.
You can help change the lack of native AsciiDoc support by creating a support case through http:https://github.com/support. This way, we won’t need a GitHub Action workflow anymore to publish AsciiDoc websites.
Tell the GitHub team that you want the choice to write in AsciiDoc, and have it handled the same way Markdown is when pushed to your GitHub Page.
Your voice counts: make it heard!
The repository requires the following structure to work correctly:
-
main or master (legacy), for markup sources and configuration. This branch can be named anything you choose, however main is a general standard used in Jekyll blogs.
-
gh-pages, for the generated static content hosted on GitHub Pages. This branch is the username.github.io GitHub Pages domain, which is automatically created and updated for you when the GitHub Actions workflow runs.