Asciidoctor Dev

Work in Progress - Version 0.1.29 : Oct-21-2019 10:32 AM


This web site is the result of a technology deep dive to understand Asciidoctor technology enough for create an architecture to develop and deploy this web site.

Development Architecture

Figure 1. AsciiDoctor Development Architecure

The product of the architecture is a presentation quality web site written using Asciidoctor.

  • The AsciiDoc source files written with the Visual Studio Code editor are compiled to HTML5 by the Ruby Asciidoctor Gem, and frequently viewed in a web browser during editing sessions. The files are stored in the local repository for safe keeping, and then committed to the GitHub shared repository when ready for publishing.

  • Netlify is notified of the commit to the shared repository, compiles the web site, and deploys it to the Internet.

The technology stack used to build this web site:


Belongs to the family of lightweight markup languages, the most renowned of which is Markdown. AsciiDoc stands out from this group because it supports all the structural elements necessary for drafting articles, technical manuals, books, presentations and prose. In fact, it’s capable of meeting even the most advanced publishing requirements and technical semantics.


Is a fast, open source text processor and publishing tool chain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats. Asciidoctor is written in Ruby and runs on all major operating systems.


Is a Ruby Gem, and so are Asciidoctor and AsciiDoc Gems.


Compiles and executes Gems.


Is a distributed source-code management system used in software development projects. Some of its attributes are speed, data integrity, and support for distributed, non-linear workflows and keeping track of file changes among multiple developers.


Is a web hosted repository for Git projects. It helps software teams collaborate and maintain the entire history of a projects code changes. Developers can view history of changes and go back to a previous version. It helps answer the questions who changed what, when, where, and why?.


Is a popular Application Delivery Network. It provides continuous deployment. When Netlify is notified of a commit to the shared repository, Netlify builds the web sites from the shared repository and deploys it to the web.

Visual Studio Code

Is a lightweight open source code editor which runs on desktops and is available for Linux, macOS, and Windows. Many extensions are available, and Git is built in. It can be Central Command for creating, testing, maintaining, and deploying web sites. It may be the best text editor in years.



John at johntelford dot com
Portland, Oregon

© 2019, Built with and a cast of creative APIs and apps

Web Sites

Web sites I’m building, maintaining, and deploying LLC is an Internet consulting company specializing in working with companies on hardware, software, and methodologies for developing, deploying, and maintaining web site designs.

A web site about the results of a technology deep dive to understand Asciidoctor technology enough to create an architecture for developing web sites

Displays selected photographs shot over the years and processed using Adobe Lightroom. The selected photos are uploaded to Adobe servers where they are organized into galleries ready for display on the web. The web site is a front end to the galleries.

Is about a deep dive into Progressive Web Apps (PWA) technology to gain an understanding and figure out a PWA development architecture for creating the web site. It is not about the nuts and bolts of how to create a PWA, but about the PWA development architecture and technologies used to create sites.

An opinionated tech talk blog

The core technology tools used to build, maintain, and deploy these web sites are Git, GitHub, Netlify, and Visual Studio Code.