asciidocsy-jekyll-theme 0.3.0.pre.dev

data/_docs/topics/config_r.adoc

@@ -0,0 +1,131 @@
+:page-permalink: /docs/theme/config
+= Site/Theme Configuration
+
+AsciiDocs employs YAML-based configuration for both the back-end (Jekyll build, Asciidoctor conversion, etc) and much of the front-end, populating CSS and JavaScript with data stored in people-friendlier [.term.flat-file]*flat files*.
+
+== Configuration Scopes
+
+AsciiDocsy makes distinct use of the two global [.term.variable-scope]*variable scopes* provided by Jekyll: `site` and `site.data`.
+Other than the `site.data` object itself, `site`-scoped variables are sourced in Jekyll configuration files.
+
+The `site.data` scope, or just "`data scope`", is sourced in the Jekyll data directory.
+This is conventionally `_data/`, but for the AsciiDocsy docs themselves, it is `_docs/_data/`.
+The location is established by the `site.data_dir` Jekyll property.
+
+All objects in both the `site` and `site.data` scopes are available anywhere Jekyll parses Liquid-formatted templates.
+However, their references (full variable names) are determined differently.
+
+=== Sourcing & Referencing
+
+Because Jekyll provides flexibility regarding how and where precisely to source objects for both scopes, *AsciiDocsy documentation uses only the dot-delimited references* and never explicit filesystem paths to the source of a data file/object being discussed.
+
+Data objects that get ingested into the `site` scope from any file bear a dot-delimited reference that respects a hierarchy starting with `site.` and then following the object's lineage without respect for the name of the source file it was derived from.
+All YAML files consumed as part of the configuration are flattened to the `site` scope.
+
+If you have a primary config file `_config.yml` in the project root and a secondary config file at `configs/secondary.yml`, then an object immediately inside either file can be expressed as `site.<object>`, where `<object>` is instead the literal name of the object being expressed.
+
+Objects in the `data` scope, on the contrary, begin with `site.data.` and continue on with (1) the path to the YAML file, (2) the name of the YAML file, and then (3) the lineage to the object inside that file.
+So a data object called `myobject` inside a file called `myfile.yml` in the folder `_data/myfolder/` would be `site.data.myfolder.myfile.myobject`.
+
+Now that we have an overview of how we _source_ and _reference_ globally scoped variables, let's look at the kinds of data we associate with each scope.
+
+== Site-scoped Configuration
+
+The `site` scope is used for configuring the Jekyll application itself and Jekyll plugins delivered as Ruby gems -- _other than the AsciiDocsy theme_ itself.
+The site scope can additionally contain miscellaneous non-plugin definitions, so long as the matter being defined does not pertain mainly to the theme or your content.
+
+The main Jekyll configuration file (by default, [.path]`_config.yml`) is the prime source for defining the configuration of Jekyll and Jekyll plugins (such as Algolia and Asciidoctor).
+
+Additional Jekyll/plugin configuration data is optimally stored as files ina  distinct directory (e.g., `_docs/_data/configs/` for AsciiDocsy's docs), for optionally appending to Jekyll commands.
+This could also be a base directory like `_configs/`.
+
+[TIP]
+To designate specific configuration files other than a single file at `_config.yml`, use the `--config file1.yml,file2.yml` option flag on the commandline.
+
+In particular, AsciiDocsy convention maintains a file at `_data/configs/services.yml` which contains a file `services.yml`, and thus an object (`services`) that contains child objects like `analytics` and `search`.
+This is for configuring plugins used to index content or distribute analytics to an external provider.
+
+While Algolia is an official plugin, your Google Analytics JavaScript might not have any back-end component at all.
+But since site analytics tracking feature have nothing to do with the site theme or the site content, it is a `site`-scoped configuration.
+Whereas the list fo JavaScript files used by AsciiDocsy is situated in the `site.data.theme` scope, as it is highly theme-specific.
+
+As you will see, the great bulk of configuration options and other AsciiDocsy goodies are defined in the `data` scope.
+
+For _site-scoped variables_ (settings), use link:https://jekyllrb.com/docs/configuration/[Jekyll's config reference] and plugin documentation (such as link:https://github.com/asciidoctor/jekyll-asciidoc[Asciidoctor's]) for guidance.
+
+== Data-scoped Configs & Content
+
+The `site.data` scope has multiple purposes, including content-related information and further configuration.
+Established purposes include:
+
+subject data::
+Structured information about your product, project, or other subject.
+Key objects include `site.data.navs`, for defining the information architecture of your site, and `site.data.terms`, for defining a glossary.
+
+theme data::
+Objects that define theme-related components, elements, and styles.
+Theme objects include `site.data.theme.navigation`, `site.data.versioning`, and `page-actions`.
+
+=== Form/Function vs Content
+
+The goal of organizing data into the `site.data.theme` scope instead of dumping it all in `site.data` is to keep _form_ and _content_ separate.
+
+Let's look at an example.
+As you might expect given their distinctness, the data objects called `nav` and `navigation` each serve a different purpose.
+
+The data object `nav` actually defines your site's navigation _content_.
+It's what goes into the navs -- the links and their labels, as well as any nested structuring.
+
+The `navigation` object, meanwhile, defines various navigation components (menus and link lists), with regard to placement, appearance, and functionality.
+
+Another example is the two `strings` objects, one directly at `data.strings` and another at `data.theme.strings`.
+The latter file is for _phrases and terms that appear in theme elements_, while the former is intended to contain _strings that might be repeated in your documentation content_.
+
+*When adding new files*, use this rule of thumb to determine placement.
+
+* [.case]*If the data modifies the _presentation_ or _functionality_ of an HTML element or the like*, locate it in `data.theme`.
+
+* [.case]*If the data is content-specific and "`portable`"*, it goes directly in the `data` scope.
+
+A good test for portability is whether it would go with you if you switched from Jekyll to another SSG or from AsciiDocsy to another Jekyll theme.
+
+For this reason, it might make sense to have a `data.versions` object that lists all the ways your product is [.term.versioning]*versioned*, and then use the `site.theme.versioning` object only to define the shape and functionality of your version handlers.
+Most version handlers can take data options directly or ingest them from a third source; the latter approach separates form from content.
+
+=== File Placement
+
+The dot-delimited reference system allows you to choose the arrangement of your Jekyll application's data files.
+While AsciiDocsy expects variables to be at a certain address, the folders, files, and objects contained in those files are up to you to order.
+
+For example, the AsciiDocsy docs application uses the path `_docs/_data/theme/versioning.yml` as the home for the `site.theme.versioning` object.
+This object contains two immediate child objects: `defaults` and `handlers`, with the latter object containing a whole list of child objects like `user-os-swap` and `theme-skin-amend`.
+
+These objects will always be referenced _in documentation_ using the same dot notation, such as  `site.data.theme.versioning.handlers.user-os-swap`.
+The data object itself could, however, be on either of these paths:
+
+* `_data/theme/versioning/handlers.yml`
+* `_data/theme/versioning/handlers/user-os-swap.yml`
+
+By author preference, the `versioning.yml` file in AsciiDocsy's case is pretty big, but there is not much savings in splitting at the next tier (`defaults` and `handlers`), and one file per version handler seems excessive.
+Your preferences may vary.
+
+[NOTE]
+Liquid markup can reference variables using dot-notation, bracket notation, or a mix.
+So the above could be `site.data.theme.versioning['handlers']['user-os-swap']`.
+AsciiDocsy source reserves this syntax for when the brackets will contain a variable string (`site.data[unquoted-variable]`) rather than an explicit (quoted) string., or when the variable name contains symbols, such as `$doc`.
+
+Now that we have covered sourcing and referencing data-scoped variables, a look at `site.data.theme` and the rest of the `site.data` scope is in order.
+
+See the <</docs/theme/config/api-reference#,Theme Configuration API Reference>> for all available objects and settings.
+
+=== Config Documentation DSL
+
+AsciiDocsy introduces a domain-specific language (DSL) for _documenting_ theme configuration and other data files.
+Any YAML object in the form of a Struct/Hash (not Arrays or Scalars) can be given a `$doc:` property to document the object and any nested objects.
+
+This novel DSL lets you describe properties, and it will even read the existing value and list it as default.
+You will see this `$doc:` syntax already used in `_docs/_data/theme/` files.
+It is processed by the nestd includes: `config-api.asciidoc`, `config-api-objects.asciidoc`, and `config-api-properties.asciidoc`.
+
+You may use this DSL to document your own data objects.
+More documentation will appear here soon.

data/_docs/topics/extend.adoc

@@ -0,0 +1,70 @@
+:page-permalink: /docs/theme/extend
+= Extending the Theme
+
+AsciiDocsy is designed to be customized without having to interfere with the core template, style, or script files.
+
+The configuration system is elaborate, enabling control of most major features via YAML-formatted files.
+Toggling features on and off and defining settings should mostly entail modifications to files of meticulously organized parameters.
+
+The rest of the customization strategy involves supplementing or replacing AsciiDocsy's core files.
+You can add <<css>> or <<javascript>>, or you can <<template-overrides,override the existing templates>> or insert your own templates inside them using <<template-hooks,"`hooks`">> embedded in the AsciiDocsy templates.
+
+== CSS
+
+AsciiDocsy uses Sass and static CSS for style sourcing.
+You are welcome to add files of either type.
+
+Use the `_sass/_custom.scss` file to take advantage of Bootstrap variables, mixins, and utilities.
+
+Use the `css/custom.css` file to override any precedent set in the cascade.
+
+Use the <<template-hooks,template extension hooks>> `css_head` and `css_tail` to add whole files to the beginning or end of the stylesheets link list.
+
+== JavaScript
+
+While AsciiDocsy is a fully JAMstack theme, its use of JavaScript to overcome the limits of AsciiDoc and HTML is JAMstack__ish__ at the very least.
+
+Bootstrap provides numerous elements that enhance the way we shape and place novel elements.
+However, jQuery (or another JS framework of your choice) is most helpful with post-render content enhancement and management.
+
+When delivering HTML, JavaScript will almost always provide you with the final say.
+
+As one example, AsciiDocsy uses JS-driven menus that dump into divs.
+The terms-list generated on topic pages that contain glossary terms is also generated this way.
+
+[[template-overrides]]
+== Template Overrides
+
+Since AsciiDocsy (post 0.3.0) is a gem-formatted theme, the core theme files are expressed at build time rather than being located in your workspace.
+Therefore, you may override any data file or template file by replacing it your local path.
+
+The typical way to replace a file is to start with its upstream source.
+Use [.cmd]`bundle info asciidocsy-jekyll-theme` to find the path to your local AsciiDocsy gem.
+Otherwise, just go to the link:{theme_repo_www}[AsciiDocsy source repo] and copy/paste the file contents into your own.
+
+[[template-hooks]]
+== Template Hooks
+
+Most of AsciiDocsy's core Liquid templates contain at least one [.term]*template hook*, letting you insert or replace code in strategic places.
+
+Anywhere a file contains syntax like [.code]`{% include hook.liquid template="template_ext" spot="#some-place" %}`, a hook is available.
+Defining this hook for your application will insert your own template into the parent template at that spot.
+
+Hooked extensions are designated in [.path]`\_data/theme/extend.yml`.
+Hooks look for [.code.tokset_hooks-var]`site.data.theme.extend.hooks.templates.<template_ext>.<spot>`, where [.tok.hooks-var]`<template_ext>` is the filename of the calling template with a literal underscore (`_`) in place of the dot before the extension.
+The last slot, [.tok.hooks-var]`<spot>`, references the `spot` argument of the hook.
+
+.Example hook objects from [.path]`_data/theme/extend.yml`
+[source,yaml]
+----
+include::{path_to_data_dir}/theme/extend.yml[tags=example]
+----
+
+<1> references an insertion point near the top of the calling file.
+
+Supplemental files can be named however you wish.
+
+[TIP]
+The `breadcrumbs_html` data object is commented out by default.
+To see this extension-hooks method in action, remove the comments and rebuild the site.
+Page breadcrumbs will be replaced by a statement.

data/_docs/topics/frontend-overview.adoc

@@ -0,0 +1,62 @@
+:page-permalink: /docs/theme/features/frontend
+= AsciiDocsy Frontend Overview
+
+The AsciiDocsy theme is not exactly groundbreaking in its layout.
+This is by design.
+
+There may be some cases when a unique format or layout is called for in documentation, but they are few and far between.
+Users want predictability.
+They want "`intuitive`" layouts where everything is where they expect.
+
+In that spirit, AsciiDocsy's layout is conventional.
+There are four navigation areas surrounding the content of each page.
+
+image::asciidocsy-nav-model.png[title="AsciiDocsy's navigation model"]
+
+Let's examine these navigation areas more closely.
+
+== Site Menus and Navigation
+
+Typically used for sitewide pages or key external links, the `#topnav` menu can accommodate a layer of nesting, if needed.
+
+=== Subject Navigation (Left)
+
+You are welcome to use the subject menu (`#subject-menu`) for anything you wish, of course, just as you are welcome to hide it.
+It is set up as generically as possible, with repurposing in mind.
+
+That said, `#leftbar`-situated nav menu is mainly intended to reference either a simple lists of topics within your subject or complex, nested combinations of links to topics and artifacts for a subject or a set of subjects.
+
+[NOTE]
+The subject menu does not at this time have a way of inferring a menu from the filesystem or even from page metadata (frontmatter).
+While this functionality is possible, I have found it clunkier than centralized "`manifest`" data files that coordinate page and topic metadata.
+
+=== Page Navigation (Right)
+
+The right sidebar contains navigation and other features relevant to the current page or topic.
+
+==== Page Links
+
+Every page with a `page` or `topic` layout has a number of optional links to alter the page appearance or submit edits.
+
+===== Data Edit Link
+
+Since some pages in an AsciiDocsy site can be sourced as data and pressed into rich-text form using Liquid templates, linking to the source data file can be helpful.
+
+image::thumb-topic-data-source-edit.png[title="AsciiDocsy lets you link to the AsciiDoc source and the underlying YAML file."]
+
+See this feature in action in the <</docs/theme/config/api-reference#,Configuration API Reference>>.
+
+==== Topic TOC
+
+The topic table-of-contents is generated by Bootstrap's scrollspy component.
+The client (browser) renders headers of designated levels into TOC items with anchor links.
+
+[NOTE]
+This feature does not use AsciiDoc's built-in TOC generator, which can still be embedded in the page itself.
+
+The TOC remains in a static position as you scroll the page, tracking your position by highlighting the appropriate item in the TOC.
+
+=== Company Navigation (Bottom)
+
+The company nav consists of up to five columns of links.
+Link hrefs can draw data from additional sources, as well.

data/_docs/topics/history-converse.adoc

@@ -0,0 +1,18 @@
+:page-permalink: /docs/theme/history-converse
+:page-title: AsciiDocsy Release History (Converse)
+:page-data-source: _docs/_data/releases.yml
+:page-canonical: /docs/theme/history/
+:page-liquid:
+= Release History
+
+[IMPORTANT]
+====
+This is an *alternate version* of the AsciiDocsy Release History, generated by <</docs/theme/config/release-hx#,ReleaseHX>>, a component of AsciiDocsy.
+ReleaseHX is fully open source, and you are welcome to use it in your project.
+
+This page is to demonstrate the transformational power of ReleaseHX, but in our case it is not an optimal arrangement for reviewing the actual release history of AsciiDocsy.
+
+*<</docs/theme/history#,See the canonical Release History>>*.
+====
+
+{% include release-hx.asciidoc rn_groupby="type" cl_groupby="part"  %}

data/_docs/topics/history-patches-merged.adoc

@@ -0,0 +1,18 @@
+:page-permalink: /docs/theme/history-patches-merged
+:page-title: AsciiDocsy Release History (Patches Merged)
+:page-data-source: _docs/_data/releases.yml
+:page-canonical: /docs/theme/history/
+:page-liquid:
+= Release History
+
+[IMPORTANT]
+====
+This is an *alternate version* of the AsciiDocsy Release History, generated by <</docs/theme/config/release-hx#,ReleaseHX>>, a component of AsciiDocsy.
+ReleaseHX is fully open source, and you are welcome to use it in your project.
+
+This page is to demonstrate the transformational power of ReleaseHX by *absorbing patch-version release documentation into the next major/minor release*.
+
+*<</docs/theme/history#,See the canonical Release History>>*.
+====
+
+{% include release-hx.asciidoc patch_policy="merge" %}

data/_docs/topics/history.adoc

@@ -0,0 +1,23 @@
+:page-permalink: /docs/theme/history
+:page-title: AsciiDocsy Release History
+:page-data-source: _docs/_data/releases.yml
+:page-liquid:
+= Release History
+
+[NOTE]
+This page was generated by <</docs/theme/config/release-hx#,ReleaseHX>>, a component of AsciiDocsy.
+ReleaseHX is fully open source, and you are welcome to use it in your project.
+
+This page tells the story of AsciiDocsy.
+This system for Release Notes and Changelog is itself novel and experimental.
+It is intended for collaborative team implementation at scale, which we try to demonstrate here as we scale up to the complexity of the v1.0 release.
+
+[TIP]
+====
+Try some alternative versions of this page:
+
+* <</docs/theme/history-converse#,Changelog sorted by part; notes sorted by type>>
+* <</docs/theme/history-patches-merged#,Patch versions merged with next major/minor docs>>
+====
+
+{% include release-hx.asciidoc log-order="changelog,release-notes" %}

data/_docs/topics/intro.adoc

@@ -0,0 +1,6 @@
+:page-permalink: /docs/theme
+= AsciiDocsy Setup & Configuration Docs
+
+include::{path_to_readme}[tags=purpose]
+
+image::asciidocsy-screenshot.png[]

data/_docs/topics/setup-bootstrap_t.adoc

@@ -0,0 +1,71 @@
+:page-permalink: /docs/theme/setup/bootstrap
+:page-togglers: user-os
+= "`Bootstrap`" this Theme
+
+Assuming you don't just want to build a site that promotes and documents the AsciiDocsy theme itself (I got this), your goal must be to apply AsciiDocsy to your own documentation set.
+
+Cool.
+The first step is to review the entries in `_config.yml` and translate them to your own application.
+
+[IMPORTANT]
+The site at `localhost:4000` will regenerate incrementally whenever you change pretty much any file in the repo.
+A key exception is `_config.yml`.
+To get site settings and `site`-scoped variables to reflect in a build, use kbd:[Ctrl+C] to stop the server, then re-run `bundle exec jekyll s`.
+
+AsciiDocsy is designed to be modified mostly through YAML configuration and datafile settings.
+See link:{theme_docs_www}/theme/config[Configuring AsciiDocsy] in the theme docs for more.
+
+== LiquiDoc Ops Integration (More Coming Soon)
+
+This theme is meant to go be embedded in the [.path]`theme/` path of a LiquiDoc Ops application (probably as [.path]`theme/asciidocsy/`).
+Repoint any Jekyll configuration settings from `theme/[<theme-name>/]` to this new path.
+
+== Deploying an AsciiDocsy Jekyll Site
+
+The build operation generates static HTML files and other artifacts that can be deployed to any static-site server.
+Most docs-as-code toolchains incorporate "`continuous integration`" and "`continuous deployment`" (CI/CD), integrating the docs build into review workflows and the timely release of the production ("`live`") site.
+
+=== Automation with Netlify
+
+My preferred out-of-box deployment with full production hosting as well as staging capabilities is definitely Netlify.
+You can sign in with your GitHub/GitLab authorization and have site up in under a minute.
+
+. Create a Netlify account.
+. Add a site.
+. Select your repo.
+. The build command ([.cmd]`bundle exec jekyll build`) and target path ([.path]`_site/`) should already be filled out.
+
+You can trigger builds through the Netlify UI or by simply merging a commit to the `main` (or other default) branch.
+
+[NOTE]
+If you set up CI/CD on another such platform, please contribute the instructions here.
+I have no affiliation with or allegiance to Netlify or GitHub.
+
+=== DIY DocOps
+
+If you or your DevOps/IT department have ideas for static-site hosting and integration into an existing CI/CD platform, this task should be fairly straightforward.
+
+==== Build Operation
+
+You defintely want to:
+
+. Require Ruby 2.4+.
+. Run [.cmd]`bundle install`.
+. Run [.cmd]`bundle exec jekyll build`.
+. Copy files from the destination dir (`_site/` by default) to your staging or production server.
+
+==== Continuous Integration
+
+You will probably also want to:
+
+* Establish build triggers for:
+** merge/pull requests (staging deploy)
+** merges to the main branch (production deploy)
+* Establish tests, perhaps starting with:
+** link:https://github.com/gjtorikian/html-proofer[HTMLProofer] for link and HTML checking
+** link:https://github.com/errata-ai/vale[Vale] for conetnt/style linting
+
+==== Deployment
+
+The site is configured to be served at a domain or subdomain root, such as `www.yourdocumentationwebsite.com` or `docs.yourcompan.io`.
+If you serve them at a path beneath such a URL, like `www.yourcompany.com/docs`, add that path to your `destination:` setting in `_config.yml` and copy from that path to your webserver.

data/_docs/topics/setup-environment_rg.adoc

@@ -0,0 +1,65 @@
+:page-permalink: /docs/theme/setup/environment
+:page-togglers: user-os
+= Setting Up a Writing/Development Environment
+
+A proper Jekyll/AsciiDocsy environment has a few prerequisites.
+
+The entire toolchain is Ruby-based, so once you have the right version of <<ruby>>, it is pretty easy to get up and running.
+
+The rest of what you'll need to have a great experience with AsciiDocsy is a <<terminal,terminal emulator>> and a <<code-editor,code editor>>.
+
+[[ruby]]
+== Ruby
+
+include::{path_to_readme}[tags=requirements-ruby]
+
+[[terminal]]
+== Terminal & Shell
+
+[.os-win]
+--
+*Windows* users still need a terminal to pass commands to the WSL shell.
+Try link:https://docs.microsoft.com/en-us/windows/wsl/install-win10#install-windows-terminal-optional[Windows Terminal], as recommended in the WSL2 setup article.
+--
+
+[.os-mac]
+For *MacOS* users who do not already have a preferred terminal, link:https://iterm2.com[iTerm2] is a common favorite.
+
+[.os-nix]
+If you are using a *Linux desktop*, I will assume you have a preferred terminal, and that it is KDE's link:https://konsole.kde.org[Konsole].
+
+=== Zsh
+
+On *all platforms*, I strongly recommend anyone new to the commandline/shell operations immediately [.tip]*install Zsh as default shell*.
+Apple made Zsh the default shell for MacOS back in link:https://www.theverge.com/2019/6/4/18651872/apple-macos-catalina-zsh-bash-shell-replacement-features[2019] due to ease of use.
+
+Zsh is basically a superset of Bash, so you can still use Bash scripting and all Bash commands, but Zsh makes it so much more intuitive and assisted.
+
+There are lots of resources to enhance the experience, including the awesome link:https://ohmyz.sh[addons package OhMyZsh]!
+Use their link:https://github.com/ohmyzsh/ohmyzsh/wiki/Installing-ZSH[Zsh install guide] to make sure you've got the best setup.
+
+[[code-editor]]
+== Code Editor
+
+Users perform most editing of AsciiDoc and YAML source files using software called a _plaintext editor_, a _code editor_, or an _integrated development environment_ (IDE).
+The distinctions are not very important, as long as they integrate with AsciiDoc and YAML.
+
+If you already have a preference, that's the editor for you.
+If you are unsure, here is a brief guide to the top contenders.
+
+VS Code::
+By far the most popular code editor today, https://code.visualstudio.com/Download[VSC]'s renowned https://github.com/asciidoctor/asciidoctor-vscode[AsciiDoc support] is maintained by the Asciidoctor community.
+Extend native YAML support with https://github.com/redhat-developer/vscode-yaml[RedHat's extension].
+
+Atom::
+Maintained by GitHub, https://atom.io/[Atom] was for years the main choice for AsciiDoc writers.
+You will want to add at least the asciidoc-language and asciidoc-preview packages.
+
+InelliJ IDEA::
+More and more people swear by this https://www.jetbrains.com/idea/download/#section=linux[freemium application] and its https://plugins.jetbrains.com/plugin/7391-asciidoc[AsciiDoc plugin] as the ultimate writing combo.
+Extend https://plugins.jetbrains.com/plugin/7792-yaml-ansible-support[YAML support].
+
+AsciiDocFX::
+This AsciiDoc-focused editor gets better all the time, and its YAML handling is on par with the others. Installers work great for every platform, even if I find Java a little clunky (same would go for IntelliJ). Give link:https://asciidocfx.com[AsciIDocFX] a try.
+
+The Asciidoctor project maintains a decent https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/#using-a-modern-text-editoride[list of "`text editors`" with AsciIDoc support] of some kind.

data/_docs/topics/setup-quickstart_t.adoc

@@ -0,0 +1,10 @@
+:page-permalink: /docs/theme/setup/quickstart
+:page-togglers: user-os
+include::README.adoc[tags=globals]
+:page-canonical: {theme_repo_www}/
+= Quickstart Demo
+
+To see AsciiDocsy and Jekyll in action, try building the demo site.
+
+// includes the DOCS repo's own README file
+include::README.adoc[tags=quickstart-build]

data/_docs/topics/setup.adoc

@@ -0,0 +1,9 @@
+:page-permalink: /docs/theme/setup
+:page-togglers: user-os
+= AsciiDocsy Setup
+
+These topics topic will guide you through the nitty-gritty of setting up AsciiDocsy with Jekyll -- either integrating it into your existing Jekyll site or starting from scratch.
+
+[.case]*_If you are already at home with Jekyll and Asciidoctor_*, try the <</docs/theme/setup/quickstart#,Quickstart guide>> or go straight to the <</docs/theme/setup/bootstrap#,Boostrapping guide>>.
+
+[.case]*_If you are new to Jekyll or Asciidoctor_*, get familiar with the <</docs/theme/setup/environment#,environment and related tools for this project>> before <</docs/theme/setup/quickstart#,installing and building>> for the first time.

data/_docs/topics/syntax-highlighter-examples_r.adoc

@@ -0,0 +1,172 @@
+:page-permalink: /docs/theme/syntax
+= Syntax Highlighting
+
+AsciiDocsy comes with syntax highlighting by Highlight.js, but Jekyll and Asciidoctor both support other highlighters, including Rouge and Pygments.
+
+[NOTE]
+AsciiDocsy will eventually incorporate all upstream-supported highlighter options.
+
+== Examples
+
+All of the following examples are taken from the Highlight.js site and are used to demonstrate how snippets of each language would look in AsciiDocsy.
+
+=== Structured Query Language (SQL)
+
+[source,sql]
+----
+CREATE TABLE "topic" (
+    "id" serial NOT NULL PRIMARY KEY,
+    "forum_id" integer NOT NULL,
+    "subject" varchar(255) NOT NULL
+);
+ALTER TABLE "topic"
+ADD CONSTRAINT forum_id FOREIGN KEY ("forum_id")
+REFERENCES "forum" ("id");
+
+-- Initials
+insert into "topic" ("forum_id", "subject")
+values (2, 'D''artagnian');
+----
+
+=== HTML
+
+[source,html]
+----
+<!DOCTYPE html>
+<title>Title</title>
+
+<style>body {width: 500px;}</style>
+
+<script type="application/javascript">
+  function $init() {return true;}
+</script>
+
+<body>
+  <p checked class="title" id='title'>Title</p>
+  <!-- here goes the rest of the page -->
+</body>
+----
+
+=== AsciiDoc
+
+[source,asciidoc]
+----
+Here is some text with a link:/[link to the homepage].
+
+Followed by some *bold* and:
+
+* An
+* Unordered
+* List
+
+definition:: list
+----
+
+=== Ruby
+
+[source,ruby]
+----
+# The Greeter class
+class Greeter
+  def initialize(name)
+    @name = name.capitalize
+  end
+
+  def salute
+    puts "Hello #{@name}!"
+  end
+end
+
+g = Greeter.new("world")
+g.salute
+----
+
+=== JavaScript
+
+[source,javascript]
+----
+function $initHighlight(block, cls) {
+  try {
+    if (cls.search(/\bno\-highlight\b/) != -1)
+      return process(block, true, 0x0F) +
+             ` class="${cls}"`;
+  } catch (e) {
+    /* handle exception */
+  }
+  for (var i = 0 / 2; i < classes.length; i++) {
+    if (checkCondition(classes[i]) === undefined)
+      console.log('undefined');
+  }
+
+  return (
+    <div>
+      <web-component>{block}</web-component>
+    </div>
+  )
+}
+
+export  $initHighlight;
+----
+
+=== JSON
+
+[source,json]
+----
+[
+  {
+    "title": "apples",
+    "count": [12000, 20000],
+    "description": {"text": "...", "sensitive": false}
+  },
+  {
+    "title": "oranges",
+    "count": [17500, null],
+    "description": {"text": "...", "sensitive": false}
+  }
+]
+----
+
+=== YAML
+
+[source,yaml]
+----
+---
+# comment
+string_1: "Bar"
+string_2: 'bar'
+string_3: bar
+inline_keys_ignored: sompath/name/file.jpg
+keywords_in_yaml:
+  - true
+  - false
+  - TRUE
+  - FALSE
+  - 21
+  - 21.0
+  - !!str 123
+"quoted_key": &foobar
+  bar: foo
+  foo:
+  "foo": bar
+
+reference: *foobar
+
+multiline_1: |
+  Multiline
+  String
+multiline_2: >
+  Multiline
+  String
+multiline_3: "
+  Multiline string
+  "
+
+ansible_variables: "foo {{variable}}"
+
+array_nested:
+- a
+- b: 1
+  c: 2
+- b
+- comment
+----