Newsletter
Join the Community
Subscribe to our newsletter for the latest news and updates
A template project for creating AsciiDoc-based websites using Jekyll.
Jekyll AsciiDoc Quickstart is a GitHub repository template for building AsciiDoc-based static websites with Jekyll, published automatically to GitHub Pages through a preconfigured GitHub Actions workflow.
Jekyll AsciiDoc Quickstart is a starting point for creating AsciiDoc-powered websites that use Jekyll as the static site generator. It takes AsciiDoc markup files as input and produces a fully built static website hosted on GitHub Pages. The template is offered as a GitHub repository template, so creating a new site means clicking "Use this template," then enabling GitHub Pages and running the publish workflow. A live example site is available at https://asciidoctor.github.io/jekyll-asciidoc-quickstart.
.github/workflows/publish.yml builds the Jekyll site with the AsciiDoc plugin on every push to main or master, then pushes the output to the gh-pages branch for hosting..adoc) instead of Markdown, with the jekyll-asciidoc plugin enabled during the build.jekyll serve locally after installing Ruby and RubyGems to preview your site before pushing..adoc posts, push to GitHub, and the site goes live on your username.github.io/repository-name URL..github/workflows/publish.yml to alter the Jekyll build or add extra publishing steps.After creating a repository from the template, you enable GitHub Pages with the "GitHub Actions" source in Settings. The included workflow listens for pushes, runs the Jekyll build with the AsciiDoc plugin, and deploys the generated content to the gh-pages branch. To work locally, install Ruby, check your Gemfile for dependencies, and run jekyll serve.
No. GitHub Pages does not whitelist the jekyll-asciidoc plug-in, so .adoc files are not rendered like Markdown posts. This template works around that limitation by using a GitHub Actions workflow to build the site before publishing.
Click the green "Use this template" button on the GitHub repository page, create a new repository, then go to Settings → Pages, set Source to "GitHub Actions," and run the "Publish to GitHub Pages" workflow from the Actions tab.
Yes. Install Ruby and RubyGems as described in the Jekyll installation docs, then run jekyll serve in your repository root. If the command fails, confirm the required gems are installed with gem list --local | grep "jekyll".
The template expects a main or master branch for markup sources and configuration. The workflow is configured to build from either branch.
Yes. You can edit .github/workflows/publish.yml to customize the build or publishing process. The included workflow is intended to work as-is, but it is a standard GitHub Actions file you can modify.
