Suggested AsciiDoc formatting stuff (general best practice stuff) #2

To consider going forward, but not required for approval of any particular PR.

I would say # 2 is the most important to me since it has real accessibility impact.

1. For AsciiDoc (.adoc) documents to be stored in and rendered in Github, consider adding conditional Github preprocessing macro to your document header:

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

The above will ensure any admonitions ("info blocks" in some other tools) that ever get added to a document will render consistently and nicely.

See Demo of some useful tips for using Asciidoc on GitHub for more.

I include this by default in all my .adoc files so I don't have to go find it if I ever want to add admonitions to a page, or use images.

2. Add more structure to documents with section levels

Github's outline view is powered by section/header structure, but it is not useful on these pages because the structure under "Queries" is flat.

Using section levels (headings) also gets you the ability to link to a specific section of the document with no extra work on your part.

2.5. For all but the simplest of documents, always insert a TOC somewhere near the top.

TOC documentation

In combination with adding section level for each query, this will give an overview of the queries on each page with the ability to jump to a specific query.

It also means structural navigation of the document is NOT solely dependent on Github's implementation of "Outline" which could go away or break at any minute. And part of the beauty of AsciiDoc is that the files can seamlessly be converted to PDF, or, with an extra step or two, many other document formats.

Example document header:

:toc:
:toc-placement!:
:toclevels: 4

(other header stuff)

= Document title

Optional short intro paragraph, after which an auto-generated TOC will appear... 

toc::[]

== Heading

blah

=== Subheading

blah blah 

==== Sub-sub heading 

blah blah blah