asciidocsy 0.3.0.pre.rc1

data/_data/theme/release-hx.yml

@@ -0,0 +1,163 @@
+$doc:
+  name: Release History (ReleaseHx)
+  desc: Template for parsing version history into Release Notes and/or Changelog
+  args:
+    rn:
+      desc: Settings for release-notes listings.
+    cl:
+      desc: Settings for changelog listings.
+    parts:
+      desc: |
+        Product components or aspects -- sub-subjects.
+
+        `name`:: A label for this part.
+        `slug`:: A key for this part.
+        `icon`:: Font icon to represent this part.
+    types:
+      desc: |
+        The kinds of changes recorded.
+
+        `name`:: A label for this type.
+        `slug`:: A key for this type.
+        `verb`:: An action word for this type.
+        `icon`:: Font icon to represent this type.
+        `text`:: A brief explainer for this type.
+    tags:
+      desc: Special attributes about recorded changes deserving of being flagged.
+    roles:
+      desc: User types affected by recorded changes.
+    cats:
+      desc: General categories for search/filtering, not for flagging.
+policy:
+  patches: flatten # flatten* or merged (shown with next minor/major revision)
+rn:
+  empty-group: show
+cl:
+  empty-group: hide
+parts:
+  - name: Layout/Styles
+    slug: frontend
+    icon: paint-brush
+  - name: Content Management
+    slug: content
+    icon: map-o
+  - name: Back-end
+    slug: backend
+    icon: server
+  - name: Documentation
+    slug: docs
+    icon: file-text-o
+types:
+  -
+    name: addition
+    verb: added
+    slug: new-feature
+    text: for new features
+    icon: plus-circle
+  -
+    name: improvement
+    verb: improved
+    slug: improvement
+    text: for changes in existing functionality
+    icon: magic
+  -
+    name: deprecation
+    verb: deprecated
+    slug: deprecation
+    text: for soon-to-be removed features
+    icon: exclamation-circle
+  -
+    name: removal
+    verb: removed
+    slug: removal
+    text: for now-removed features
+    icon: minus-circle
+  -
+    name: bugfix
+    verb: fixed
+    slug: bugfix
+    text: for any bug fixes
+    icon: wrench
+tags:
+  -
+    name: Security
+    slug: security
+    text: for changes made to secure a component
+    icon: lock
+    tone: danger
+  -
+    name: Privacy
+    slug: privacy
+    icon: user-secret
+    tone: dark
+  -
+    name: Experimental
+    slug: experimental
+    text: for possibly unstable or temporary features
+    icon: flask
+    tone: warning
+  -
+    name: Compliance
+    slug: compliance
+    text: for changes made to conform to regulations
+    icon: balance-scale
+    tone: success
+  -
+    name: Breaking
+    slug: breaking
+    text: for changes that violate backward compatibility
+    icon: unlink
+    tone: warning
+  -
+    name: Deprication
+    slug: deprecation
+    text: announces future cancelation/removal of feature/capability
+    icon: warning
+    tone: warning
+roles:
+  - name: Admin
+    slug: admin
+    text: Maintainer of a product instance.
+  - name: Designer
+    slug: designer
+    text: Shapes an application of the product for a user instance.
+  - name: Author
+    slug: author
+    text: End user, documentation contributor.
+cats:
+  - name: User experience
+    slug: ux
+    text: Enhances the UX of an interface/procedure.
+  - name: Code refactor
+    slug: refactor
+    text: Involves radical improvement of the code; may carry bug risks.
+  - name: User-authored
+    slug: user-author
+    text: Derived from a user contribution of code or documentation.
+  - name: Free and open-source
+    slug: foss
+    text: This component is openly authored and permissively licensed.
+defaults: # default values for properties, organized by block
+  revision: # establish default values for properties
+    down: true # whether to show download link
+  item:
+  note:
+  both:
+patterns: # value patterns for properties, organized by block
+  revision: # value patterns for the revision block
+    vcode:        "v{{ rvsn.code }}"
+    heading:      "Version {{ rvsn.code }}, {{ rvsn.date }}"
+    download-url: "{{ site.source_www }}/releases/tag/v{{ rvsn.code }}"
+    download-label:
+      standard:   "Get {{ rvsn.code }}"
+      latest:     "Get v{{rvsn.code}} -- Latest release! icon:flag-checkered[]"
+      go-to-latest: "Get {{ latest_release.code }} icon:flag-checkered[]"
+    admonition: |-
+      The following flag{% if flags.size > 1 %}s{% endif %} appear{% unless flags.size > 1 %}s{% endunless %} in this release.
+  item: # changelog-item-specific settings
+  note: # release-note-specific settings
+  both: # release-note- and changelog-specific settings
+    ticket-link: # vars: tick
+      href: "{{ site.subject_tickets_www }}/{{ item.tick }}"
+      text: "Issue #{{ item.tick }}"
+      icon: github

data/_data/theme/scripts.yml

@@ -0,0 +1,43 @@
+$doc:
+  desc: Defines references to JavaScript resources.
+  args:
+    head: {type: Array,desc: "JavaScript files to include in the `head` element."}
+    tail: {type: Array,desc: "JavaScript files to include in the `tail` div."}
+head:
+  - slug: jquery
+    href: /assets/js/jquery-3.3.1.min.js
+  - slug: popper
+    href: https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js
+    meta:
+      integrity: sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49
+  - slug: bootstrap
+    href: https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js
+  - slug: jquery-cookie
+    href: /assets/js/jquery.cookie.js
+  - slug: algolia-instantsearch
+    href: https://cdn.jsdelivr.net/npm/instantsearch.js@4.8.3/dist/instantsearch.production.min.js
+    meta:
+      integrity: sha256-LAGhRRdtVoD6RLo2qDQsU2mp+XVSciKRC8XPOBWmofM=
+  - slug: autocomplete
+    href: https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.min.js
+  - slug: algoliasearch-3
+    href: https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js
+  - slug: anchors
+    href: /assets/js/anchor.min.js
+  - slug: navgoco
+    href: /assets/js/jquery.navgoco.js
+  - slug: bootstrap-toc
+    href: /assets/js/bootstrap-toc.js
+  - slug: highlight-js
+    href: /assets/js/highlight.pack.js
+  - slug: asciidoctor
+    href: /assets/js/asciidoctor.min.js
+  - slug: asciidocsy-tabber
+    href: /assets/js/tabber.js
+  - slug: asciidocsy-toggler
+    href: /assets/js/toggler.js
+  - slug: asciidocsy-semantics
+    href: /assets/js/semantics.js
+tail:
+  - slug: asciidocsy-tail
+    href: /assets/js/tail.js

data/_data/theme/semantics.yml

@@ -0,0 +1,14 @@
+$doc:
+  desc: Defines inline and block-level semantic elements
+inline:
+  role:
+    term: # here 'term' is the name of the role
+      show:
+        icon:
+          text: fa fa-info-circle
+          tilt: 15
+          spin: true
+        spot: "#sidebar-right"
+    # next role here
+blocks:
+  admonitions:

data/_data/theme/strings.yml

@@ -0,0 +1,13 @@
+$doc:
+  desc: |
+    Theme strings organized by container block/element.
+    Documentation in source file only.
+footer:
+  $doc: {desc: Strings for the footer of the document.}
+  title: Your Branding
+  tagline: Your brand tagline.
+  madewith: Sourced in AsciiDoc and YAML. Generated with Jekyll, Asciidoctor, and AsciiDocsy.
+  copyright: (C) 2021 Your Copyright
+see-also:
+  $doc: {desc: Strings for the see-also segment}
+  title: See Also

data/_data/theme/styles.yml

@@ -0,0 +1,8 @@
+$doc:
+  desc: Custom styles for elements of the theme
+nav-site:
+  position: fixed
+logo:
+  width: 50px
+color:
+  theme-primary: "#30638e"

data/_docs/snippets/example_tabset-source.adoc

@@ -0,0 +1,60 @@
+// tag::raw[]
+[.tabber-tabset.tabs-data-format-tabber]
+--
+[source,yaml,role="tabber-pane pane-data-yaml"]
+----
+include::./example_tabset-source_data.yml[]
+----
+[source,json,role="tabber-pane pane-data-json"]
+----
+include::./example_tabset-source_data.json[]
+----
+--
+// end::raw[]
+// tag::marked[]
+[.tabber-tabset.tabs-data-format-tabber] // <1>
+--
+[source,yaml,role="tabber-pane pane-data-yaml"] // <2>
+----
+\include::./example_tabset-source_data.yml[]
+----
+[source,json,role="tabber-pane pane-data-json"] // <3>
+----
+\include::./example_tabset-source_data.json[]
+----
+--
+// end::marked[]
+// tag::xml-raw[]
+[.tabber-tabset.tabs-data-format-tabber]
+--
+[source,yaml,role="tabber-pane pane-data-yaml",title="YAML Data *"]
+----
+include::./example_tabset-source_data.yml[]
+----
+[source,json,role="tabber-pane pane-data-json"]
+----
+include::./example_tabset-source_data.json[]
+----
+[source,xml,role="tabber-pane pane-data-xml",title="XML Data **"]
+----
+include::./example_tabset-source_data.xml[]
+----
+--
+// end::xml-raw[]
+// tag::xml-marked[]
+[.tabber-tabset.tabs-data-format-tabber]
+--
+[source,yaml,role="tabber-pane pane-data-yaml",title="YAML Data *"] // <1>
+----
+\include::./example_tabset-source_data.yml[] // <2>
+----
+[source,json,role="tabber-pane pane-data-json"]
+----
+\include::./example_tabset-source_data.json[]
+----
+[source,xml,role="tabber-pane pane-data-xml",title="XML Data **"]
+----
+\include::./example_tabset-source_data.xml[]
+----
+--
+// end::xml-marked[]

data/_docs/snippets/example_tabset-source_data.json

@@ -0,0 +1,16 @@
+[
+   {
+      "app": "Asciidoctor",
+      "use": "THE AsciiDoc markup converter",
+      "url": "https://www.asciidoctor.org",
+      "git": "https://github.com/asciidoctor/asciidoctor",
+      "vrsn": "2.0"
+   },
+   {
+      "app": "Jekyll",
+      "use": "world-class static-site generator (SSG)",
+      "url": "https://jekyllrb.com",
+      "git": "https://github.com/jekyll/jekyll",
+      "vrsn": "4.0"
+   }
+]

data/_docs/snippets/example_tabset-source_data.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<root>
+  <row>
+    <app>Asciidoctor</app>
+    <use>THE AsciiDoc markup converter</use>
+    <url>https://www.asciidoctor.org</url>
+    <git>https://github.com/asciidoctor/asciidoctor</git>
+    <vrsn>2.0</vrsn>
+  </row>
+  <row>
+    <app>Jekyll</app>
+    <use>world-class static-site generator (SSG)</use>
+    <url>https://jekyllrb.com</url>
+    <git>https://github.com/jekyll/jekyll</git>
+    <vrsn>4.0</vrsn>
+  </row>
+</root>

data/_docs/snippets/example_tabset-source_data.yml

@@ -0,0 +1,10 @@
+- app: Asciidoctor
+  use: THE AsciiDoc markup converter
+  url: https://www.asciidoctor.org
+  git: https://github.com/asciidoctor/asciidoctor
+  vrsn: '2.0'
+- app: Jekyll
+  use: world-class static-site generator (SSG)
+  url: https://jekyllrb.com
+  git: https://github.com/jekyll/jekyll
+  vrsn: '4.0'

data/_docs/snippets/example_toggles.adoc

@@ -0,0 +1,25 @@
+// tag::user-os[]
+[.os-win]
+--
+This site works great on Windows 10, and probably on Windows 7, and likely even on Windows XP.
+Windows often requires extra/special instructions for developer-oriented stuff.
+
+Windows users are encouraged to explore WSL2 for access to a true Unix-like system right inside their main OS.
+--
+
+[.os-nix]
+--
+This site was built on a Linux desktop, and it probably looks great on FreeBSD.
+I personally want Mac and Windows users to know that, but other stuff might be noise to non-Linux users, so why rub their noses in it?
+--
+
+[.os-mac]
+--
+MacOS always makes AsciiDocsy look terrific.
+--
+
+[.os-mac.os-nix]
+--
+The author of AsciiDocsy strongly prefers Unix-like systems, but they would never want Windows users to see such a statement.
+--
+// end::user-os[]

data/_docs/snippets/handlers-table.adoc

@@ -0,0 +1,40 @@
+// tag::table-head[]
+[cols="1a,2,2,4,3a",options="header"]
+|===
+| verb
+| target
+| forms
+| description
+| sources
+// end::table-head[]
+// tag::table-row-amenders[]
+s| <</docs/theme/config/versioning/amenders#,amend>>
+| URL/head elements
+| select icon:caret-square-o-down[], buttons icon:dot-circle-o[]
+| Change a string in a DOM element or add your own function.
+| `version-handler.html`, your custom JS
+// end::table-row-amenders[]
+// tag::table-row-swaps[]
+s| <</docs/theme/config/versioning/swaps#,swap>>
+| tokens in the text
+| select icon:caret-square-o-down[], buttons icon:dot-circle-o[]
+| Change the expression of a token already rendered in HTML.
+| `version-handler.html`
+// end::table-row-swaps[]
+// tag::table-row-toggles[]
+s| <</docs/theme/config/versioning/toggles#,toggle>>
+| element classes in the text
+| buttons icon:dot-circle-o[]
+| Show/hide elements of classes.
+| `version-handler.html`, `js/main.js`
+// end::table-row-toggles[]
+// tag::table-row-tabsets[]
+s| <</docs/theme/config/versioning/tabsets#,tab>>
+| a block element in place
+| tabs icon:folder-open-o[]
+| Determine which block in tabset to show in pane.
+| `js/tabber.js`
+// end::table-row-tabsets[]
+// tag::table-tail[]
+|===
+// end::table-tail[]

data/_docs/snippets/reference-cluster.adoc

@@ -0,0 +1 @@
+{% assign objs = page.cats-list | split: "," %}

data/_docs/topics/advanced-applications_c.adoc

@@ -0,0 +1,50 @@
+:page-permalink: /docs/theme/advanced
+= Advanced Applications
+
+AsciiDocsy is intended to accommodate highly complex product sets.
+In fact, it is designed to suit the LiquiDoc Ops framework, which handles multi-product, multi-version documentation sites through single-sourcing.
+
+== Multi-subject Management
+
+For most technical documentation sites, the _subject_ is a product.
+And for a significant subset of these product-focused documentation sites, more than one product needs to be covered in the same place.
+
+At the very least, there must be commonality and continuity between product [.term]*docsets*.
+This is true even if at first the docset sourcing and primary toolchains differ drastically between products.
+At the point of delivery ("`deployment`"), the docs must come together under a common _theme_.
+
+That theme is AsciiDocsy.
+
+A typical AsciiDocsy site combining multiple products will draw content from distinct sources at build-time.
+
+[.case]_If you keep all your documentation source in one repo_, that might be your codebase that also contains the AsciiDocsy theme, your Jekyll configuration, and other required files.
+In this case, you should have a directory inside the docs-source root called something like `content/`, with subdirectories named after the products as slugs, such as `content/frontend-app` and `content/backend-db`.
+
+[.case]_If you source your documentation in separate product repos_, you still need a _main docs repo_.
+In this case, the objective is to construct a directory structure as recommended above at build-time, presumably from locally cached sources.
+
+Some teams opt to treat product repos as Git submodules or subtrees in relation to the main docs repo.
+Another option is to maintain a cache of cloned repos in a directory ignored by the main docs repo's Git configuration -- something like `.subjects-cache`.
+
+In either of these cases, at build-time, just copy the relevant files from those subrepos or cached repos into an ephemeral (also Git-ignored) _build directory_.
+Be sure to include that build directory in your Jekyll configuration as `source:`.
+
+An alternative to subrepos or ephemerally cached clones, some teams opt to maintain copies of the product docs source in a file server, such as a CDN (content-delivery network).
+These files are pulled in over VPN at build-time and similarly cached between builds.
+
+One way or another, the task at hand is to get the AsciiDoc, image, and other files from those product repos into your main docs repo in order to build the docs.
+
+Each source should be a single root-level directory, probably called `docs/` or `docs/topics` in the product repo, and written as something like `_build/frontend-app/` in the main docs repo.
+This directory must at the very least include AsciiDoc (`.adoc`) files.
+It can also include relevant subcirectories like `images/`, `snippets/`, etc.
+
+It is highly recommended that each product team also maintain a data file for the repo -- something like `docs/topics/_dataset.yml` or `docs/topics/_manifest.yml`.
+This file can also sit in the ephemeral subject-based (product) directory.
+Or each such file can be moved to the Jekyll data directory (probably `_data/`), renamed to make it distinct (for instance, `_data/frontend-app.yml`, `_data/backend-db.yml/`).
+Now there would be data accessible at scopes like `site.data.frontend-app` and `site.data.backend-db`.
+
+== Multi-revision Management
+
+Another major type of subject divergence AsciiDocsy is designed to handle is sequential versioning, technically known as [.term]*revisioning*.
+
+More on this topic coming in v0.2.0.

data/_docs/topics/config-api_r.adoc

@@ -0,0 +1,21 @@
+:page-permalink: /docs/theme/config/api-reference
+:page-data-source: _config.yml
+:page-liquid:
+:page-layout: reference
+= Theme Configuration API
+
+[NOTE]
+This reference is highly experimental.
+I've only spent about 2 hours coding this as an example of a novel domain-specific language (DSL) reference parsed from YAML by Liquid into AsciiDoc for rendering as HTML (or PDF, etc).
+
+Consider this to be rudimentary documentation generated from data structures found in `_config.yml`.
+This would be better generated from a _schema_-like version of these data objects, referencing them with metadata about each block of properties in each feature object.
+Instead, we are using the objects directly, supplemented by an optional `$docs` objects embedded in the config data structure.
+
+Also, due to object nesting, lots more recursive processing needs to happen.
+The truth is, a simple configuration file that can be commented inline and must be edited in place is not great fodder for an API reference, but I wanted to demonstrate it.
+
+But do look at the AsciiDoc and YAML sources (see links to the right icon:right-arrow[]) for this page if you need inspiration for your own complex content.
+
+// Liquid transclusion tag
+{% include config-api.asciidoc %}

data/_docs/topics/config-release-hx.adoc

@@ -0,0 +1,4 @@
+:page-permalink: /docs/theme/config/release-hx
+= ReleaseHx Product History Feature
+
+Documentation slated for 0.2.1.

data/_docs/topics/config-search-algolia.adoc

@@ -0,0 +1,77 @@
+:page-permalink: /docs/theme/config/search/algolia
+= Algolia Search Integration
+
+A cloud account with Algolia is required to implement Algolia as a cloud-search provider.
+
+[WARNING]
+By default, AsciiDocsy's own Algolia application is configured in the repo.
+You will be able to generate local content packages for it, or query its live indices, but you will not be able to write (push) to the cloud indices.
+
+The link:https://www.algolia.com/users/sign_up[Algolia signup] is free.
+You only start paying when you use certain thresholds of index space or query bandwidth.
+
+AsciiDocsy's implementation of Algolia's Jekyll plugin (link:https://github.com/algolia/jekyll-algolia[source]) (link:https://community.algolia.com/jekyll-algolia/getting-started.html[docs]) and instantsearch form (link:https://community.algolia.com/instantsearch.js/documentation/[docs]).
+
+== Search Settings
+
+The `site.algolia` object, by default defined in `_config.yml`.
+
+.Object: `site.algolia`
+[source,yaml]
+----
+include::_config.yml[tags=algolia]
+----
+
+Additionally, each search form on your site needs some more data.
+By default the search forms draw this info from objects inside `site.data.theme.search`, such as `search-site` and `search-subject`.
+These objects need properties for `show.spot` and `meta.index`.
+
+.Object: `site.data.theme.search.site`
+[source,yaml]
+----
+include::_data/theme/search.yml[tags=search-site-core]
+----
+
+[WARNING]
+These settings are only used for _searching_.
+
+[[index-settings]]
+== Index Settings
+
+In order to _index_ your site's content, you will need an auxilliary configuration file with the `algolia` object at the root.
+This configuration file can be called instead of or in addition to the main Jekyll config.
+
+._docs/_data/configs/search-index-pages.yml
+[source,yaml]
+----
+include::_data/configs/search-index-pages.yml[]
+----
+
+The search is performed by running a `jekyll algolia` operation with your private API key added.
+
+=== ENV Variable
+
+One option is to add your key explicitly to the commandline as an environment variable.
+
+.Example commandline ENV variable option
+ ALGOLIA_API_KEY=01d664977165dbf4cded12199738fabf bundle exec jekyll algolia --config _config.yml,_data/configs/jekyll-search-x.yml
+
+=== Stashed File
+
+Alternatively, stash the key as in a file called `_algolia_api_key` (no file extension).
+
+.Entire contents of file `_algolia_option_key`
+ 01d664977165dbf4cded12199738fabf
+
+[IMPORTANT]
+Be sure to add this file to your [.path]`.gitignore` file.
+
+In this case, you may run the following.
+
+.Example commandline with no ENV variable
+ bundle exec jekyll algolia --config _config.yml,_data/configs/jekyll-search-x.yml`
+
+[TIP]
+To test your indexing process without pushing to Algolia, add [.cmd]`--dry-run` (or simply [.cmd]`-n`)
+
+For full configuration options, refer to the link:https://community.algolia.com/jekyll-algolia/options.html[Jekyll community documentation].

data/_docs/topics/config-search.adoc

@@ -0,0 +1,47 @@
+:page-permalink: /docs/theme/config/search
+= Indexing and Searching Content
+
+Any search system requires a way to index and query the content in the site.
+There are several options for serious search solutions, many of which we intend to build into AsciiDocsy for easy configuration "`out of the box`".
+
+== Search Utilities
+
+Each solution below comes equipped with an indexing component and a query form/results feature.
+
+=== Cloud-based Search
+
+Cloud-search providers host indexes of your content and provide a RESTful API for queries.
+
+Algolia is a provider of freemium cloud-based search.
+It is highly affordable for small docsets, but at larger scales it might get pricey to index numerous versions amounting to thousands of pages.
+The company maintains its own Jekyll plugin, which AsciiDocsy incorporates.
+Learn to <</docs/theme/config/search/algolia/#,integrate your AsciiDocsy site with Algolia>>
+
+Algolia's main competition seems to be link:https://swiftype.com[Swiftype from Elastic].
+Many documentarians swear by Swiftype, and its pricing may work better at certain scales.
+
+The only self-hostable option in this field is link:https://www.elastic.co/downloads/elasticsearch[ElasticSearch's main offering], which can be integrated using a link:https://github.com/omc/searchyll[Jekyll plugin called Searchyll].
+
+=== Client-based Search
+
+An option popular with lightweight Jekyll sites is link:https://jekyllcodex.org/without-plugin/search-lunr/[Lunr.js] (or link:http://elasticlunr.com[ElasticLunr.js]), a front-end-only solution that puts the whole index into the client package.
+Lunr.js is as ingenious as it is clunky, and it is a common solution for simple docs sites or internal-only docs.
+
+One or more of these JS-only solutions will make it into AsciiDocsy by 1.0.
+
+== Search Strategy
+
+Searchable content is organized by index.
+Generally, one index equals one subject to be searched.
+Whether using cloud- or client-based search, organizing your indexes will be key.
+
+One strategy is to build a separate site for each batch of content to be indexed.
+So if you have 3 products with 3 supported revisions each, you probably want to have 10 indices: 1 index for each revision of each product, and a tenth for pages or general site search.
+
+How you then choose to organize the search functionality comes down to user experience (UX).
+You can use one field that searches the current revision of the current project _and_ all site pages.
+Alternatively, you can separate search into non-subject page search and subject-topic searches.
+
+[TIP]
+For cloud-search on a tight budget, if revision-level indices are too expensive to maintain, you can feed all versions' search fields query an index based on the latest content.
+But assuming significant variance among supported products, a client-based solution might be your best hope for getting results that don't frustrate the user.

data/_docs/topics/config-semantics.adoc

@@ -0,0 +1,45 @@
+:page-permalink: /docs/theme/config/semantics
+:page-tags: semantics,inline-semantics
+= Configuring Inline Semantics
+
+AsciiDocsy enables robust use of inline semantics, as documented in the link:/docs/style/asciidoc/semantics[Inline Semantics Style Guide].
+
+There are a few ways you can customize these semantics, both meaning and presentation.
+
+The default semantic roles AsciiDocsy provides -- _term_, _cite_, _path_, _cmd_, and so forth -- is relatively arbitrary.
+Some I have seen or used in production, others (like _case_) are more experimental.
+
+These are not coded into the theme in any way except with CSS.
+Simply do not use any role you do not wish to.
+You may also add your own or alter the existing roles however you prefer.
+
+Use your `custom.css` file to modify the rendered presentation, and use your own style policy to alter the source markup (the quote characters).
+
+Which quotes are used to contain your text (backtick, underscore, aserisk, or hash) will determine the fallback styling for any rendering not styled by your semantic CSS, such as Asciidoctor PDF output with no styling designated for the roles.
+
+Role class definitions are not attached to the specific HTML elements used by Asciidoctor.
+This means for other roles, you can swap the quote characters in order to affect the rendered formatting with italics (underscore), bold (asterisk), or no styling (hash symbol).
+You can even use a combination of bold and italic as quotes: [.code]`pass:[*_bold and italic_*]`.
+
+[TIP]
+Do not make more semantic roles than your authors will use properly, and do not use them so frequently that they make the page too busy or awkward.
+Remove any roles that are not in regular use.
+
+== Inline Semantics in Action
+
+Take for example the AsciiDocsy "`Purpose`" section of the README, which is [.term.inclusion]*included* for rendering in the topic template [.path]`_docs/topics/theme_intro.adoc`.
+
+.Purpose section of [.path]`README.adoc`
+[source,AsciiDoc]
+----
+include::{path_to_readme}[tags=purpose]
+----
+
+This code renders like so in the AsciiDocsy theme:
+
+****
+include::{path_to_readme}[tags=purpose]
+****
+
+Without the AsciiDocsy theme -- such as in unthemed PDF or link:{git_source_www}/blob/main/README.adoc#purpose[on GitHub] -- styling "`degrades`" gracefully, falling back on formatting designated by the quotes syntax.
+In this case, the terms marked with the `case` role are bold _and_ italic on GitHub, whereas the term marked `buz` is italic on GitHub even though it is unitalicized in AsciiDocsy.