AsciiDocsy

This is a major fork of the awesome Docsy Jekyll port done by VanessaSaurus, itself a fork of Google’s Docsy theme for Hugo. The last commit from the Docsy Jekyll version was retained for convenient diffing and just to maintain full credit.

Now serving

v0.2.0 (2021-07-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

• [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)

• [refactor] CSS to Sass (#24)

• [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

• [refactor] as Ruby gem/Jekyll plugin (#31)

• [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.

AsciiDocsy has hooks and features specifically designed to take advantage of such applications when built using the LiquiDoc Ops framework, but it should be handy for any Jekyll site, AsciiDoc-based or not.

🔥

If you intend to use AsciiDocsy for Markdown in addition to or rather than AsciiDoc content source, at this time you will need to undo some of the configuration changes made for this demo repo. Between your existing configuration file and VanessaSaurus’s Docsy Jekyll theme source and docs, you should be able to adapt this codebase to render .md files of your flavor.

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

Alternatively, build your own locally.

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.

Build the Docs

With a Ruby environment in place, these steps should generate the website sourced in the AsciiDocsy theme repository.

1. Clone (or download and inflate) this repo.

   Clone

   git clone [email protected]:DocOps/asciidocsy-jekyll-theme.git

   Download & inflate

   

   💡	Use git clone [email protected]:DocOps/asciidocsy-jekyll-theme.git my-asciidocsy-project to name the containing directory something other than asciidocsy. Or clone normally and freely rename the directory at any time.

2. Install Ruby dependencies.

   bundle install

   If Bundler is not installed, gem install bundler, then repeat bundle install.

3. Change to the new directory.

   Example

   cd my-asciidocsy-project

4. Generate and serve the demo site.

   bundle exec jekyll serve

You should now be able to view the site at http://localhost:4000 in any local browser.

You will find the generated files at _site/.

💡	Learn more about applying AsciiDocsy to your use case in the Bootstrapping guide.

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. 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. I left a copyright notice in the templates for now, but will happily negotiate attribution while this project is in pre-release status. Much of the code in the _includes/ and _layouts/ directories remains from the original.

📎	While this project is not an active fork of Docsy Jekyll, it was forked at commit # b5f32a1, if you want to run a diff.

The remainder of the code is released under both MIT and Apache 2.0 licenses. 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.

See the .data/dependencies.yml file in this repository for a listing of third-party code.

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