docops / asciidocsy-jekyll-theme

Jekyll/AsciiDoc port of Docsy theme for scalable technical documentation projects

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.

asciidocsy-jekyll-theme's Issues

Integrate Lists.js

This library is awesome. There are lots of cases for giving users the ability to easily rearrange tables and lists.

https://listjs.com

Related topics need to be smarter

NOTE: This ticket is partly resolved so has been edited to reflect new objective.

Apparently I never finished the code to display like-tagged topics as "Related Topics", which currently sits at the bottom of each topic as a lone header: "See these other topics".

I stopped because I was trying to figure out the best way to implement this feature. Do we enable a page variable that lists tags, and then cross-reference every so-tagged topic? This is pretty standard.

Do we enable specific entries for links that would not match the tags?

I'd love some feedback on this.

Git info variable

Hugo has a Git info variable that fetches the last commit associated with a contents page. Is it possible to do the same in Asciidocsy?

Add icons to display elements where configured

The _config.yml file contains lots of references to icon: property that do not actually render an icon in the output. These are for FontAwesome icons, but they should also work with other systems. They must insert the literal class icon (.icon) plus the value of this icon property.

Subject menu `active`/`open` highlights are a little off

Our Navgoco implementation (the left nav menu) uses the classes active and open to keep track of what submenus to expand and what active links to highlight. It is supposed to strongly highlight the link to the page the browser is on (this works) and subtly highlight the submenu containing the page the browser is on (this partly works).

Refactor CSS to Sass

I'm not terribly upset with the state of the theme's CSS, as such things go for a rapidly changing theme. But before it gets out of hand, I want to organize it a way I find more ideal.

I had started trying to use the original Hugo Docsy's SCSS (Sass) files, which was sort of working, but there were some quirks I did not have the patience to deal with (or even document). This would not be a terrible place to start.

Docsy also maintains a vendor/ path for Bootstrap and FontAwesome, which I like. We can do this in #32. Once we're in Sassville, we don't have to impose preferred colors in the CSS, and we can get Bootstrap out of the repo. Let's add Asciidoctor Stylesheet Factory to the vendor/ bin as well.

Finish adding a tabbed panel content changer

This is kind of a flagship feature, and I was bummed to not have it done by 0.1.0, but it was getting convoluted. The version I am working from is not jQuery and needs to be converted, which is not my forte. Nevertheless, this one is on me.

• tabs show/hide one or more overlayed blocks of content

• sourced entirely in standard AsciiDoc, rendered w/ JS

• configurable under site.features

• degrades gracefully for PDF/no-JS rendering

For short browser windows, there is a background-colored eement obscuring the content of the right side bar

Finish the config API templates

I've started a system for self-documenting the configuration structure to some extent. It's mostly just an experiment, but it needs to be more complete before we can assess usefulness.

Publish theme in a GitHub release

Publish the next version of asciidocsy theme in a release

removing Gemfile.lock from .gitignore

I don't think it makes sense to have Gemfile.lock in .gitignore, since the point of the lock file is to provide a reproducible build of dependencies needed to run a working site. I spent a couple of hours trying to debug why bundler was producing inconsistent builds when experimenting between jekyll 3.8 & 4.2, committing relevant changes as I go (as one should), until I noticed git wasn't tracking changes to Gemfile.lock after running bundle lock.

asciidocsy-jekyll-theme/.gitignore

Line 2 in 623eeab

Gemfile.lock

On mobile, site and subject navs should be collapsable menus

The mobile version has 2 obvious problems: a margin along the right side and menus that are way too big at the top.

The menus should be collapsed to a hamburger button so the reader sees some content before scrolling.

How to adjust site footer height

There's a lot of unoccupied vertical space in the site footer that I wouldn't mind shortening

Add a way for the TOC to use draw non-header IDs

It would be handy to have objects in a reference load in the page-nav's TOC, even if they don't have their own headers, which most will not.

The solution here could possibly include adding hidden headers, though that's not perfectly elegant.

What I'm thinking is if you have a DL reference, for instance...

[#setting-a.toc-add]
setting-a:: Here is the definition of setting-a.

[#setting-b.toc-add]
setting-b:: Here is the definition of setting-b.

Add true "toggle" (checkbox on/off) capability to toggle handlers

The original idea for toggle handlers included facet-style toggles for classes independent of others. So, a direct show/hide toggle for one class at a time, checkbox style.

I don't think there's any complex logic in here -- if multiple competing classes are assigned to an element/block, we might want the ability to select an all or one paradigm, whereby a class will show only when all classes are toggled on or when at least one is. We probably want to incorporate that as much as we can to leave the options wide open.

This did not make it into #48, but it should get in by 1.0.

Add labels to button-based handler controls

Handlers with buttons cannot display their text/icon labels. The labels should be similar to those for selectboxes, but I wasn't immediately able to do that in #48 so I punted.

Ensure accessibility (a11y) of entire theme

Before 1.0, this theme needs a thorough audit and correction to conform to a11y standards.

The "iconic" theme creates a black bar across the top of the page that interferes with the page heading

EPIC: Gemify the theme

I was going to put this off to just before 1.0, but that was before I realized all the advantages of packaging this project as a Ruby Gem.

I'm not sure all of these steps are required, but they constitute the best practice.

• Sassify the CSS (#24)
• Reorganize assets (#28)
• Improve vendor source handling (#32)

Once those are complete, we can add a gemspec and make a few other changes, and document the whole thing in the Readme. In fact:

• Documented the new format in Readme.

The big question here is how to handle the AsciiDocsy docs themselves. Do we add them to the gem or do we just keep them in the project for testing and for building the main site? I need to look at how others handle this.

This epic will be disruptive, so I'm going to do it after 0.1.1, maybe as part of 0.2.0, but definitely by 0.3.0.

Enable replacing feature and other config objects from the site scope to other objects

Right now, most features and other theme settings draw from the site scope defined by Jekyll configuration files.

It would be nice to provide (at the point of expression in layout/include templates) an alternate source for any object. The object would need the same required properties, but this would enable proviing configuration in data files.

WORKAROUND: For now, the optimal means of achieving this is to source the different site-scoped objects in separate files and list all files in your Jekyll command using bundle exec jekyll build --config file1.yml,file2.yml. To break up the giant site.features scope into multiple files, you''ll need to compile multiple child objects into one, which is not handled by AsciiDocsy alone.

Algolia logo/link missing from search forms

Algolia requires their logo for free-tier use of their services, which we are using. We definitely need to get that into the template.

add docs for installing theme as submodule

Having the theme maintained as a submodule would allow for easier updates to the theme as new releases get published

Make a way to `asciidocify` YAML text properties before converting to JSON

In several places, we will use JS/JSON on the very front end to display significant blocks of text drawn from YAML. It would be great if we could asciidocify this first, where applicable.

This probably means re-doing the jsonify Jekyll/Liquid filter, one way or another. Maybe an asciidoc-jsonify filter? Or, we could just use an include and iterate through the object and asciidocify as we go. That wouldn't be too hard or resource intensive.

Print-friendly feature behaving quite unfriendly

There is a link in each topic page that is intended to drop the sidebars and give you an uncluttered display of the topic article.

It should behave something like the "Print entire section" on a Docsy site.

Print-friendly button not working

Clicking the "Print-friendly" button causes the navbar to disappear for about a half second, but then reappears.

Finish developing AsciiDoc-sourced "landing page" layout

While I still intend to reintroduce a YAML-driven landing page (#5), I have come to believe there is still hope for an AsciiDoc-sourced landing-page layout. The current version at https://asciidocsy.netlify.app is a far cry from good, but I only spent 2 or 3 hours on it. How far is it really from something like OpenAPI Generator's landing page, which I quite like? I think all of these elements, plus something clever with admonitions, and I bet it could look pretty good sourced only in AsciiDoc. And I do think that would be easier to spin up when you need to throw together a quick website for a software project, which i want AsciIDocsy to be suited for.

So I would like to return to this landing page in some form, perhaps before I get to #5.

Change 'togglers' to 'switchers' and enable real toggles (on/off)

I already dislike how what I'm calling "togglers" is work in this theme, and I'm sick of mixing up "toggles" and "togglers".

Also, as a pedant, it bothers me that this utility does not so much toggle content as it switches content.

So let's call them switchers, but let's also make it possible to have them be simple on/off toggle capability using a checkbox rather than radio button concept.

Liquid filter `asciidocify` causes Jekyll build error

Though I can confirm the nifty asciidocify filter provided by the jekyll-asciidoc plugin works in a fresh Jekyll repo, something in this codebase is causing an error I've never encountered.

To reporoduce, in _includes/footer.yml, just change one of the entries that now reads asciidocifyxme to asciidocify and run bundle exec jekyll build.

Liquid Exception: asciidoctor: FAILED: <stdin>: Failed to load AsciiDoc document - no implicit conversion of Symbol into String in <project-path>/_layouts/default.html

This is a Ruby TypeError thrown inside Asciidoctor as called by the Convert module in jekyll-asciidoc plugin. I cannot figure out for the life of me what could be causing this to behave differently. Even if you just pass it an explicit String (e.g., {{ "some _asciidoc_ string" | asciidocify }}), it rejects it as a Symbol type.

New repo/structure for AsciiDocsy docs deployment once theme is gem?

For the 3.0 release, in which AsciiDocsy will be packaged as a Ruby gem (#31), we will want the AsciiDocsy docs themselves (the documentation that covers the AsciIDocsy theme), to not be based in the root dir of any Jeklyll application using this theme.

For any use of the theme gem, including AsciiDocsy docs's own use, we want the application root to be definitional and for everything in it to override. So we either need to clean up the directory structure and have a distinct Jekyll application inside the gem file structure, or we need to separate the docs out and have a distinct repo use the the way any other application would. This has the advantage of demonstrating a relatively organic use of the theme. Unfortunately, it means another repo, and I think a self-documenting gem is really what's called for, so we'll probably just have a docs/ dir that can be used for Jekyll executions against the content inside it, with a _config.yml file there that does not interfere with the config for an app that might call the gem.

move "Changes so far" to a CHANGELOG

The Changes so far section is rather verbose and seems a bit TMI for the average user looking to adopt the asciidocsy theme. This issue is a suggestion to move that section to a CHANGELOG file

baseurl not prepended to links/resources for sites not deployed at root of a domain

I've tried running a local build of the asciidocsy theme via a docker image running ruby v2.6 & bundler v2.2.15, but can't seem to get it to properly render. (see option 1 on capsulecorplab/asciidoctor-docker#3 (comment))

Otherwise, the local Jekyll server seems to work fine

Add landing page layout & includes

I've never had a client ask me for a landing page as part of a documentation theme. Nevertheless, there are a few reasons I want AsciiDocsy to include a robust landing-page capacity.

• I really like landing pages.
• I need a landing page to promote AsciIDocsy, and it would be weird to use another theme to promote this theme.
• I already have a landing page theme (used here) that I put tens of hours of work into -- not just the front end, either; the config is elaborate.
• A lot of the best documentation themes have halfway-decent landing pages either built (like Docsy) in or at least used to demo/promote their theme.

The landing page theme I've already made for one case (but not yet generalized or open-sourced) is not done mainly with AsciiDoc. In fact, the only AsciiDoc at all is inside strings of text, which are nearly all stored in YAML objects that define the sections.

Here is some sample markdown driving that site.

The first thing that I did was create templates (or convert, from Agency and Airspace themes) for the different segments. These templates required lots of arguments when included, so I created elaborate includes like the following:

{% include features.html
  id         = "ops"
  title      = "The Unity Platform"
  desc       = "Bringing technical writers and engineers together."
  nodes      = site.data.features.primary %}

{% include gridfolio.html
  id         = "showoff"
  title      = "For Documentation Worthy of Your Product"
  desc       = "LiquiDoc Ops is JAMstack-based, offering complete front-end freedom.<br/>It also ships with a killer versioning-ready docs theme."
  nodes      = site.data.folio.output.portal %}

{% include quote.html
  id         = "alicia-quote"
  text       = "After searching and testing options for almost a year, I helped design and pilot LiquiDoc Ops. Not only has the LiquiDoc Ops toolchain proven to be a refreshingly nimble and sophisticated way for me to manage our content, but my developer colleagues love working with it."
  attribution= "Alicia Duncan, Lead Technical Writer, <a href='https://www.digi.com/resources/documentation/digidocs/embedded/index.html' target='_new'>Digi International</a>" %}

{% include features.html
  id         = "features-secondary"
  title      = "Enterprise- and Suite-ready"
  desc       = "LiquiDoc Ops is designed for documenting complex products with awkward version-divergence problems by accommodating their necessarily complex sourcing schemes."
  nodes      = site.data.features.secondary %}

Each of these blocks of code of course calls a file that embeds the content inside HTML directly. That works pretty well, mind you, but honestly Liquid is the LAST of all the markups I use that I actually want to write content in. Liquid is really not for content -- especially not its {% include %} tagging process. Ew.

That's why I came up with a YAML-driven solution. Here i an example of the source of content that populated some of these includes.

primary:

  - name: Free and Open
    text: All components are free/freemium and open standards/FOSS
    icon: folder-open-o
    role: proprietary

  - name: Source Controlled
    text: No binary database, nothing proprietary, everything in Git
    icon: git
    role: proprietary

  - name: Version Aware
    text: Docs and tools that know all your products' permutations
    icon: sort-numeric-desc
    role: markdown

  - name: Enterprise Scale
    text: LiquiDoc Ops means first-class docs across the organization
    icon: industry
    role: markdown

  - name: XML Free!
    text: Lightweight markup means all the power with none of the bloat
    icon: code slash
    role: proprietary

  - name: Writer-friendly Tools
    text: Clide is the unifying CLI utility for command-line phobes
    icon: pencil
    role: markdown

secondary:

  - name: Full Spectrum
    text: Developer docs (including internal) and user-facing docs
    icon: address-card
    role: proprietary,markdown

  - name: Output Anything
    text: Helpsites, manuals (HTML + PDF), JSON, even JS-driven presentations
    icon: file-image-o
    role: proprietary,markdown

  - name: Output Continuously
    text: CI with instant delivery and deployment, for staging and production
    icon: rocket
    role: proprietary

  - name: Frameworked
    text: Libraries, conventions, and utilities for rapid development
    icon: briefcase
    role: markdown,proprietary

  - name: Strategic Divergence
    text: Built-in options for handling edition/version differences
    icon: code-fork
    role: markdown

  - name: RBAC
    text: Roles-based access control, for workspace/UI sanity
    icon: user-times
    role: markdown

I have not seen anyone else do this, so it might be a terrible idea, but I found it really rewarding.

Now, much as I prefer authoring in YAML over Liquid, my favorite format for authoring is of course AsciiDoc. The problem is, however, that just as Markdown does not make great sense for technical authoring, AsciiDoc does not make a great source for landing pages.

The truth is almost certainly that no single content markup format is or could ever be ideal for a landing page. But even the semantics of AsciiDoc are all off, so we'd almost be better off creating a dreaded domain-specific language (DSL) for landing pages. Well, for me, that just means using YAML with some semantic intent, which is what I've done here.

The landing page currently in use here is actually my second attempt to create a landing-page layout/theme that could be driven by AsciIDoc only, with optional PDF output (because why not?), perhaps with very small snippets of passthrough (verbatim) HTML code, for stuff that wouldn't work good in PDF anyway and could thus be conditioned out. I am ready to call this second earnest attempt a failure. I have considered creating a different set of AsciiDoc conversion templates, but that feels like pouring lots more work into an idea that just isn't good enough to warrant the effort.

So I think I'm going to introduce my novel Landing page method and the basic theme that makes it work, right here inside AsciiDocsy. It should work independently of the rest of the theme, in fact, so you could use it for just a landing page, as I have.

Reorganize `site.features` (and maybe other) config objects

I initially thought the idea of putting most theme-defining data objects in the site scope -- meaning defined in one or more config files -- made a lot of sense, just to have an elegant structure and not use the _data/ dir for theme-defining stuff.

Now I think it's just annoying and too restrictive. Since there is no way to declare multiple config files from within a config file (you have to use the CLI's --config folder/file-one.yml,folder/file-two.yml,etc argument), it's not easy to break up the config file without adding lots of noise to the commandline. This can easily be remedied by the techniques most shops employ in their build routines, where long CLI commands don't matter, but I want AsciiDocsy to be a good authoring experience right out of the box, which means keeping CLI commands as simple as possible.

This leaves us with the option of moving some or all of these to the _data/config/ path, which for the AsciiDocsy site itself is _docs/_data/theme/ -- another part of the reason I like keeping this out of the data path. But I do think this is the best move. This gives the user complete control over which objects to store together. Even though you have to maintain the hierarchy/tree, with Jekyll's data scope, we have the option to store EVERYTHING in a _data/theme.yml file or split things up into _data/config/navigation.yml or even _data/config/navigation/breadcrumbs.yml and so forth.

So now site.features will be site.data.theme.features.

Except I think I also want to get rid of the extra tiers in the features object, starting with eliminating the category features itself. The actions block is probably also superfluous. If we flatten the objects down, we need no _data/config/features/ path, let alone _data/config/features/actions/.

Add a dark theme

I cannot believe I'm only just now adding this, but this theme absolutely should have a version with light text on a dark background. This is the style I prefer personally, when done right. Admittedly, I have never done it, as no customer has asked me for it, but I would love to have all my docs in a site like Jekyll's docs or even GitHub's dark theme.

Also wondering if we should stop using "skins" as a way to describe the "look and feel" of the very front-end. It doesn't feel great to use terms like "dark" and "light" with that word in this context.

This should obviously wait until after #24, but I think it is a goal for relatively early (0.3.0?).

Asciidoctor keyboard macro not working

I've run into this issue before, and I'm also sure this was working previously in the theme. It's supposed to be pretty simple: turn on the :experimental: and use the macro.

I don't understand why it sometimes fails and Google is silent.

Move `images/`, `js/`, and `css/` to `assets/` path

The conventional way to package a Jekyll theme (and maybe the required way to do it as a Ruby gem?) is as follows:

├── _layouts/
├── _includes/
├── assets/
│   ├── css/
│   ├── images/
│   └── js/
├── _config.yml
├── asciidocsy.gempsec
├── Gemfile
└── README.md

You won't catch me using Markdown for a Readme in this lifetime, but the rest seems worth sticking to. This is basically a deprecation notice on the lack of a base directory assets/. I did this originally because LiquiDoc Ops had a concept of assets as well, and I did not want them to get confused. (Additionally, on some level it bothers me to call image, JS, and CSS files "assets" but exclude template files -- this could just be me.) I believe the concept of content assets is coming out of LDOps anyway, so it just makes good sense to standardize around this method and call the site files "assets".

Option for redirecting landing page to docs/

Some documentation projects may not need a landing page, in which case it'd be useful to redirect directly to docs/

At mobile widths, the top nav dropdowns do not appear immediately: you have to scroll the area to see the selections

Separate the "site search" and "subject search" in AsciiDocsy docs

The site-nav search field is supposed to search the non-product pages of the site (or maybe those AND the product pages?).

Right now they both search everything. Break these down into 2 indexes and make them search the right stuff.

Table of content path: manifest.yml?

Hello,
I apologize in advance because this ticket isn't related to an issue, but rather a question about the usage of the theme. I got acquainted with Jekyll and "Documentation Theme" developed by Tom Johnson. But I wanted to make it compliant with AsciiDoc instead of Markdown, that's how I discovered and installed this project, which is amazing, btw!

I'm currently trying to understand the structure and how items are organized and regarding the TOC, I've found that it is available under "manifest.yml". However, what if I want to target another file as a TOC? My point is to keep the actual file as a backup and replace it with another file, for instance "my-new-toc.yml". I think it might be easier to target the TOC that will be displayed in the "Subject nav". I haven't found it in the main config file.

What am I missing?
Thanks for your feedback!

Add child topics list and prev / next links to topic footer based on subject nav

Use a little jQuery to glean the parent/child/sibling topics and provide links in the topic footer (bottom of the <main> content container in a topic page).

• ↑ Previous: Parent Topic Title (for a first-child topic)
• ← Previous: Sibling Topic Title
• Next: Sibling Topic Title →
• Next: First Child Topic Title ↓ (for parent topics)

Also generate a list of child topics when a topic has kids in the menu and use that in place of related links (or in addition to?).

Make these configurable, of course.

Add version selector feature

This feature is really just a URL selector. You feed it options, and it browses to the parallel subpath of a new version path.

So if you're at <docs.domain.com>/superproduct/v2.1/getting-started, the switcher will send you to the same URL but with v2.1 swapped out for another version.

Any number of these can exist on a page, each effectively targeting a different part of the URL.

The only complicated aspect of this is how to build it into the theme's own docs, which are currently unversioned. So this may not get a proper demo until after it is released. Keeping track of your versioned content is far more complicated than providing the front-end switcher for it.

Feedback form not yet interactive

The plan is to have the feedback form use Netlify's simple form capture service, which is free and works without a ton of setup.

That said, whatever cursory setup I tried did not stick.

Additionally, we need a smarter response system than whatever script this is all based on. Let's have options and the echo the user gets based on choice.

Remaining layout issues

The layout has some bugs. I will collect relatively minor issues in this ticket in case I get a burst of energy. Happy to split off if anyone wants to bite one or more off.

• The footer is inside the main container because it was not sticky to the bottom outside it. But it needs to span the entire screen -- looks dumb with space around it.

Please suggest any layout/CSS issues that you notice in the theme, which is also supposed to be responsive. The docs should look great on mobile devices, of course.

Add `nest` extension hook to nav menus

I have not really thought this one through, but it came up as I was documenting the nav menus, so I wanted to pin it on the board.

I believe all of the manually configurable menus (site nav in the header, subject nav in the left sidebar, and company nav in the footer) could accommodate additional nesting.

I have run a quick test on Navgoco (subject nav), and it can handle at least another tier of nesting. I am just not sure I want to support that.

The Bootstrap-driven site nav can definitely handle more nesting. See https://bootstrap-menu.com/detail-multilevel.html. This can look rather nice, but is it ever necessary? I haven't been asked to implement anything that hardcore for a site menu, but it wouldn't be hard.

But I might have to put my foot down before trying this in the footer. There is plenty of room down there, though stream-of-consciousness I guess I can fathom wanting to have lots of links in the footer but keeping it sparse at first glance from a design perspective.

Anyway, the issue is placing an extension hook at the deepest point of nesting, in case you want to continue the iteration in your own templates.

Highlight.js is not highlighting AsciiDoc syntax (of all things)

This was working at some point, but now it is not. Other languages work (see https://asciidocsy.netlify.app/docs/theme/syntax-highlighting). Asciidoctor is doing its job and creating the right class...

Generate xref attributes for all topics in manifest

Cross-references are a big problem in most static-based websites, and this is not resolved by adding AsciiDoc to the mix, even though AsciIDoc has xrefs built in. At the time of conversion, each page is treated like a distinct document, and Asciidoctor does not know what other documents are, let alone where they are.

This is the reason to use a manifest that generates menus and also records some metadata for each topic, so there is a central dataset that understands the information architecture and knows all the paths.

To render hyperlinked cross-references (xrefs)in this theme (or any jekyll-asciidoc-driven site), we use syntax like <</path/to/topic#,Topic Title or Other Text Here>>. This means we must know the exact URL of the resource and its title, and if those change, we'll have to search-and-replace to catch xrefs.

Alternatively, we could pre-generate a big set of xrefs and store them and make them available as AsciIDoc attributes (variables). For example, <<{xref_topic-slug-here}>> could render an xref just like the previous, conventional syntax. Or use <<{xref_topic-slug-here_notitle},some arbitrary text>> if you don't want to render the title of the referenced toipic.

That is the simple part. The hard part is loading them for each document build. Every document build ingests AsciiDoc attributes from site.asciidoctor.attributes, but those are sourced as static YAML files that won't exist at the top of the build when they're required.

Alternatively, we can generate an attributes.adoc file (using a Jekyll include), and then we can embed that at the top of each topic as an AsciiDoc include (I think?), but in this case we would need a reference this include in any file that uses the xref variables. I don't think there's a way to use layouts or any other global feature to ingest the attributes on a per-topic basis.

The only other option I can think of at this time is to create a plugin that preprocesses the manifest into a list of AsciiDoc attributes and ingests it. This might be optimal, and then it would apply to any theme that wanted to use it, right out of the box.

Improve vendor source handling

When we're delivering this theme as a gem, we don't want a bunch of unaltered vendor code in the package. Create a vendor/ or preferably assets/vendor/ path and a way to get necessary upstream code into that path before build-time. I have admittedly not done this before, but I'm going to require it for the Gemification epic (#31).

Or maybe I'm wrong about this. Feedback or research should yield a confident answer.

Stop Asciidoctor from appending `.html` to xrefs

Just need to add blank :outfilesuffix: doc attribute to config.

Add Lunr.js support back into theme

I removed Lunr.js because it was interfering with Algolia, but I want to put it back in for three reasons.

1. I want something to work right out of the box with a config setting, if not by default.
2. While it's very weak for indexing/searching technical content, Lunr.js is pretty good for pages, so it could be used for a pages-only search, which I plan to enable.
3. Someone has already requested it.