Asciidoctor Jet

About

Asciidoctor Jet is a ready-to-use jet black themed template for building static websites using Asciidoctor with features and fonts added to the default Asciidoctor template.

Getting started is very straightforward!

Features

PWA
- Custom install prompt
Themes
- Theme switcher
  - Dark mode (Jet black)
  - Light mode
- First load theme depends on the browser theme and if toggled, is thereafter set as per user preference.
Lazy loading of images
- Subject to browser support.
Fonts
- Montserrat
- PT Mono (Only for code snippets.)
Back to top button
Custom scrollbar
The repository includes a workflow to build and deploy the site on GitHub Pages.

Live Demos

Sites using the Asciidoctor Jet template

Raise an issue on the repository to be featured here! (Please add a link to the site.)
Make sure to add the asciidoctor-jet label/topic to the site’s repository for visibility!

Using Asciidoctor Jet

Getting Started

Install Asciidoctor.
Use this template.
Explore the file structure.
Add content.
Run the command sh build.sh in the root directory of the project to build the site to the build directory.
Serve the built site locally to check if all is good.
Push to GitHub and a workflow should automatically build and commit files to the gh-pages branch, which can be deployed using GitHub Pages.

Adding Content

Asciidoctor syntax is supported.
Explore the default file structure of the template.
Create a file in the content directory and include it in index.adoc using the include::path/to/file.adoc[] include directive.
- Feel free to customize the project structure as per needs, but make sure to make corresponding changes to the .github/workflows/build-deploy-website.yaml file in the repository, so that GitHub Actions is able to build and deploy the website properly.
Images can be added using the image macro.
- Example:

Serving the Site Locally

After running the sh build.sh command, the site is built out to the build directory. It has to be served from there.

There are various ways to serve file locally. Run any of the following commands from the root directory of the project.

Using the NPM package http-server is preferred.

$ npx http-server "build"

# OR

$ npm install --global http-server
$ http-server "build"

The NPM package serve can be used.

$ npx serve "build"

# OR

$ npm install --global serve
$ serve "build"

The Python module http.server can also be used.

$ python -m http.server

# OR

$ python3 -m http.server # python<version> -m http.server

File Structure

The main content of the website resides in the src directory and the entry point for Asciidoctor is the index.adoc file in the src directory.

The default structure of the src directory

src
├───content
│   └───adding-content.adoc
├───static
│   ├───css
│   ├───img
│   └───js
├───docinfo-footer.html
├───docinfo.html
├───index.adoc
├───manifest.webmanifest
├───robots.txt
└───service-worker.js

Contributing

Contributors are welcome!
For any bugs or feature requests/modifications, feel free to raise an issue if it hasn’t already been raised.
Go through the CONTRIBUTING.md file for local development environment setup instructions.
Feel free to contact the maintainer for any issues.
Check the changelog for changes in particular versions.