AsciiDocsy Jekyll Theme (Gem)

Now serving

v0.3.0 (2021-09-21)

Figure 1. Screenshot of AsciiDocsy theme

Purpose

AsciiDocsy is designed by a technical documentation specialist who builds bespoke AsciiDoc platforms for world-class enterprises.

On the front end, AsciiDocsy delivers. Designed to meet the technical documentation deployment needs of full-scale, multi-product software companies, AsciiDocsy remains fully aware that all such enterprises start small and still need world-class docs.

On the back end, AsciiDocsy unifies. The codebase brings together developers and technical writers, allowing the latter to achieve momentous feats in collaboration with the developers whose work they document.

Pre-1.0 History and Roadmap

AsciiDocsy will probably reach “general availability”/v1.0 (GA) status sometime after v0.4.0 is out, which will hopefully be late 2021. Until that point, backward compatibility is not guaranteed, but AsciiDocsy will try to make no breaking changes between major releases starting at v1.0.

1.0 Objectives

The following are areas where AsciiDocsy’s author thinks good GA-ready software meets a high standard but that AsciiDocsy presently does not yet measure up.

extreme configurability

There should never be a need to modify template files just to make minor changes. Everything should be defined in data files. The system is in place for this as of v0.2.0, but lots of settings and strings need to be moved into these files.

front-end quality

The jQuery/JavaScript I write is fairly rudimentary. Fortunately, the challenges are also pretty straightforward, but it will still be best if a JS specialist goes over the code and maybe writes some tests. Another challenge is to make sure all HTML meets accessibility standards.

back-end quality

Dependency management for the entire LiquiDoc Ops toolchain must be sensible and seamless. Vendor code must be separately manageable, including as independently maintained forks.

clean, well-documented source

Mainly thinking of YAML and Liquid code here, lots of these source files need proper headers and style review.

Changes so Far

• [added] AsciiDoc integration

  • jekyll-asciidoc plugin & configs

  • Asciidoctor styles and skins

• [refactored] as Ruby gem/Jekyll plugin

• [refactored] CSS to Sass

• [added] Algolia search integration

  • default search results page

  • instantsearch

  • multi-index ready

  • site search & subject search in separate fields

• [added] entire versioning suite

  • tabbed panes for switching content in place

  • toggles to show/hide all text/blocks w/ certain classes

  • token swaps to change front-end variables on/after page load

  • HTML DOM amender for altering HEAD elements

• [added] sophisticated, data-file-based theme configuration

  • data-scoped configs for all theme features, settings, strings, etc

  • simplistic system for documenting data objects inside YAML files

• [added] feature-rich "ReleaseHX" release history template & data format

• [added] Highlight.js syntax highlighting w/ syntax styles

• [added] “Toggler” feature to show/hide page elements by role

• [added] inline AsciiDoc semantics

  • custom styling for terms with semantic roles

  • popovers for known glossary terms (try it!)

  • “terms on this page” listing (JS)

• [added] new docs for AsciiDocsy

• [added] example writing/templating style guides

• [added] rudimentary AsciiDoc-based “landing page” layout

• [refactored] flatten assets path into root

• [refactored] data structure for configuration of features, services, etc

• [added] scrollspy page TOC

• [removed] example and stub files

• [removed] Lunr.js (for now)

• [removed] docs for Docsy Jekyll

• [removed] unnecessary templates (such as alerts.html, doc.html)

• [changed] default Git branch to main

• [changed] tab indents to spaces

• [added] explicit breadcrumb rewrites

See the AsciiDocsy Release History for more.

Revision 1.0 Targets

• [add] full-featured, YAML-driven landing-page layout & components (#5)

• [improve] Vendor-code integration: (#32)

  • SCSS files (Asciidoctor, Bootstrap, Font-Awesome, Highlight.js, et al)

  • JS (JQuery, Bootsrap, components)

  • Native extensions (Asciidoctor, Jekyll, Liquid)

  • new syntax highlighter options

• [add] Strings management with Liquid- and Asciidoctor-parsed strings sourced as YAML

• [add] Lunr.js back in as a backup/secondary search (#8)

• [add] Custom admonition blocks including several AsciiDocsy templates

• [add] DITA/Diátaxis-like semantic handling of topic types (task, concept, reference)

  • specialized layouts by topic type

  • suggested pages based on sibling topics of other types

• [add] GDPR notice

  • banner and/or modal w/ dialog

  • user selects permitted cookie types

  • feature actually suppresses unpermitted cookies

• [add] a dark theme option (user-controlled if you wish) (#35)

• [add] call-to-action (c2a) modal

• [add] search results page w/ 3rd optional instantsearch field

• [improve] feedback form with follow-up query

• [add] sufficient unit and integration tests

• [improve] and finalize dependency/upstream license handling

1.0 Stretch Goals

• [add] Reveal.js slideshows

• [add] PDF rendering

• [add] Configurable search with new options

  • ElasticSearch support via Searchyll

  • ElasticLunr.js?

• [add] option to build data-driven left navs from frontmatter

• [add] policy-based content toggles for user roles

Usage

Out of the box, this theme is ready for a somewhat plainly structured Jekyll application, with AsciiDoc support and tons of additional features.

📎

As of version 0.3.0, AsciiDocsy ships as a gem-formatted Jekyll plugin. All core AsciiDocsy files are now stored in the gem, not your application repository. You only need local paths and files such as _includes/, _layouts/, assets/css/, _data/, and so forth, when you wish to override a default/core file.

Documentation for this theme can be found at https://asciidocsy.netlify.app/docs.

Quickstart

Assuming you have a proper Ruby runtime environment installed, all you need to do is install dependencies and run the Jekyll command.

Requirements

Other than a Ruby runtime environment, this codebase installs all dependencies using Bundler.

💡	Check for a current Ruby version using ruby -v.

If you do not have Ruby installed, use Jekyll’s installation instructions.

💡	Windows 10 users are strongly encouraged to use this guide to running Jekyll on Linux via WSL.

💡	MacOS and Linux users are encouraged to install and manage Ruby using rbenv.

📎	All else being equal, we recommend you install the latest stable release, so Ruby 2.7.x or 3.0.x (where x is the latest patch version). Jekyll 4.0.0 and the jekyll-asciidoc plugin both require Ruby 2.4.0 or later.

Production Environment Details

The demo/docs site included in this repository generates a site at https://asciidocsy.netlify.app. This site is built and served for free by Netlify.

Deploying

The live site at https://asciidocsy.netlify.app/docs automatically generates and deploys each time a commit is merged to the main branch.

Search Indexing

The search indexing procedure is manual at this time, though we will move it to a GitHub Action before long.

There are two indexes: asciidocsy-pages and asciidocsy-topics. Each has its own custom configuration in _docs/_data/configs/.

You must have the Admin-only private key to write files to the Algolia index. See Algolia Search Config: Index Settings for specifics.

The indices must be processed separately. Here are the commands:

Site search

bundle exec jekyll algolia --config _config.yml,_docs/_data/configs/search-index-pages.yml

Subject search

bundle exec jekyll algolia --config _config.yml,_docs/_data/configs/search-index-topics.yml

Contributing

AsciiDocsy is open for contributions. I plan for it to be a primary project with regular, ongoing maintenance, as I expect to use it for multiple clients over the next 5-15 years.

I will work up contributor guidelines and PR templates well before v1.0. Please standby.

Please don’t hesitate to create an issue or pull request in the meantime!

Contribution Notes

Since I’ve received a couple of small pull requests from folks, I should probably track my conventions and process here to minimize frustration.

Right now I am developing on trunk branches just so I can keep releases straight. I will find a better way to do this, but for now I am trunking for each upcoming release, including patches. So it’s trunk-0.2.0, trunk-0.2.1, trunk-0.3.0, etc. These branch off main, and PRs can be merged to the trunk- branches.

If you wish to contribute a bugfix, PR against a patch-revision trunk branch (like 0.1.x). If you are proposing a new or improved feature, PR against a minor-revision trunk branch (like 0.x.0). If no such branch exists, create one on your own or message me.

Documentation-only patches may be merged directly to the main branch for realtime deployment. These changes will be brought into trunk branches through frequent rebasing.

Licensing

All sources of copyrighted material incorporated into this theme are duly licensed and attributed, falling under MIT or Apache 2.0 permissive licenses. See the NOTICE file in this repo for a complete listing. Most cases of third-party source code showing up in this codebase will be transitioned by release 1.0 vendor code as dependencies to be hosted elsewhere.

An exception to individually attributed code snippets is the Docsy Jekyll theme by VanessaSaurus. Some of the code in the _includes/ and _layouts/ directories remains from the original.

Basically, if you fork this codebase, know that it comes without warranty, and please leave a trail back to those whose work you’re building on if you release something that contains our code.

The other exception is Navgoco, the jQuery menu generator, which is licensed under the BSD-3-clause license. The Navgoco project has been dormant for years, so we will swap this navigation out for something equivalent.

All other dependencies are Ruby gems. See Gemfile.lock for all versions of all Bundler-managed dependencies.