asciidocsy 0.3.0.pre.rc1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/LICENSE +201 -0
- data/_config.yml +66 -0
- data/_data/theme/alerts.yml +21 -0
- data/_data/theme/blocks.yml +33 -0
- data/_data/theme/forms.yml +72 -0
- data/_data/theme/navigation.yml +53 -0
- data/_data/theme/page-actions.yml +83 -0
- data/_data/theme/policies.yml +68 -0
- data/_data/theme/release-hx.yml +163 -0
- data/_data/theme/scripts.yml +43 -0
- data/_data/theme/semantics.yml +14 -0
- data/_data/theme/strings.yml +13 -0
- data/_data/theme/styles.yml +8 -0
- data/_docs/snippets/example_tabset-source.adoc +60 -0
- data/_docs/snippets/example_tabset-source_data.json +16 -0
- data/_docs/snippets/example_tabset-source_data.xml +17 -0
- data/_docs/snippets/example_tabset-source_data.yml +10 -0
- data/_docs/snippets/example_toggles.adoc +25 -0
- data/_docs/snippets/handlers-table.adoc +40 -0
- data/_docs/snippets/reference-cluster.adoc +1 -0
- data/_docs/topics/advanced-applications_c.adoc +50 -0
- data/_docs/topics/config-api_r.adoc +21 -0
- data/_docs/topics/config-release-hx.adoc +4 -0
- data/_docs/topics/config-search-algolia.adoc +77 -0
- data/_docs/topics/config-search.adoc +47 -0
- data/_docs/topics/config-semantics.adoc +45 -0
- data/_docs/topics/config-switcher_r.adoc +33 -0
- data/_docs/topics/config-tabber_r.adoc +49 -0
- data/_docs/topics/config-toggle_r.adoc +20 -0
- data/_docs/topics/config-versioning-amenders_r.adoc +76 -0
- data/_docs/topics/config-versioning-swaps_r.adoc +193 -0
- data/_docs/topics/config-versioning-tabsets_r.adoc +51 -0
- data/_docs/topics/config-versioning-toggles_r.adoc +42 -0
- data/_docs/topics/config-versioning.adoc +134 -0
- data/_docs/topics/config_r.adoc +131 -0
- data/_docs/topics/extend.adoc +70 -0
- data/_docs/topics/frontend-overview.adoc +62 -0
- data/_docs/topics/intro.adoc +6 -0
- data/_docs/topics/setup-bootstrap_t.adoc +71 -0
- data/_docs/topics/setup-environment_rg.adoc +65 -0
- data/_docs/topics/setup-quickstart_t.adoc +10 -0
- data/_docs/topics/setup.adoc +31 -0
- data/_docs/topics/syntax-highlighter-examples_r.adoc +172 -0
- data/_docs/topics/toolchain.adoc +79 -0
- data/_docs/topics/upgrade-0-3-0.adoc +49 -0
- data/_includes/_settings.liquid +2 -0
- data/_includes/_variables.sass +12 -0
- data/_includes/breadcrumbs.html +20 -0
- data/_includes/breadcrumbs_alt.html +6 -0
- data/_includes/config-api-objects.asciidoc +23 -0
- data/_includes/config-api-properties.asciidoc +29 -0
- data/_includes/config-api.asciidoc +29 -0
- data/_includes/feedback.html +59 -0
- data/_includes/footer-links_sup.html +5 -0
- data/_includes/footer.html +59 -0
- data/_includes/gdpr-message.html +41 -0
- data/_includes/google-analytics.html +11 -0
- data/_includes/head.html +74 -0
- data/_includes/header.html +22 -0
- data/_includes/hook.liquid +26 -0
- data/_includes/nav-site.html +30 -0
- data/_includes/nav-subject-menu.html +49 -0
- data/_includes/page-links.html +45 -0
- data/_includes/path-active.liquid +18 -0
- data/_includes/release-hx-change.asciidoc +7 -0
- data/_includes/release-hx-changes-listing.asciidoc +14 -0
- data/_includes/release-hx-note.asciidoc +54 -0
- data/_includes/release-hx-notes-listing.asciidoc +16 -0
- data/_includes/release-hx-revision.asciidoc +86 -0
- data/_includes/release-hx.asciidoc +57 -0
- data/_includes/scripts.html +8 -0
- data/_includes/search-form.html +113 -0
- data/_includes/see-also.html +17 -0
- data/_includes/social-links.html +10 -0
- data/_includes/string-eval.liquid +38 -0
- data/_includes/tail.html +7 -0
- data/_includes/theme-api-object-sub.asciidoc +4 -0
- data/_includes/theme-api-object.asciidoc +35 -0
- data/_includes/version-handler.html +245 -0
- data/_includes/versioning-controls.html +88 -0
- data/_layouts/default.html +94 -0
- data/_layouts/landing.html +28 -0
- data/_layouts/page.html +9 -0
- data/_layouts/post.html +8 -0
- data/_layouts/reference.html +6 -0
- data/_layouts/search.html +110 -0
- data/_layouts/topic.html +19 -0
- data/_sass/_asciidocsy.scss +698 -0
- data/_sass/_custom.scss +3 -0
- data/_sass/bootstrap/_alert.scss +51 -0
- data/_sass/bootstrap/_badge.scss +54 -0
- data/_sass/bootstrap/_breadcrumb.scss +41 -0
- data/_sass/bootstrap/_button-group.scss +163 -0
- data/_sass/bootstrap/_buttons.scss +137 -0
- data/_sass/bootstrap/_card.scss +289 -0
- data/_sass/bootstrap/_carousel.scss +197 -0
- data/_sass/bootstrap/_close.scss +41 -0
- data/_sass/bootstrap/_code.scss +48 -0
- data/_sass/bootstrap/_custom-forms.scss +507 -0
- data/_sass/bootstrap/_dropdown.scss +191 -0
- data/_sass/bootstrap/_forms.scss +330 -0
- data/_sass/bootstrap/_functions.scss +86 -0
- data/_sass/bootstrap/_grid.scss +52 -0
- data/_sass/bootstrap/_images.scss +42 -0
- data/_sass/bootstrap/_input-group.scss +193 -0
- data/_sass/bootstrap/_jumbotron.scss +17 -0
- data/_sass/bootstrap/_list-group.scss +149 -0
- data/_sass/bootstrap/_media.scss +8 -0
- data/_sass/bootstrap/_mixins.scss +47 -0
- data/_sass/bootstrap/_modal.scss +229 -0
- data/_sass/bootstrap/_nav.scss +120 -0
- data/_sass/bootstrap/_navbar.scss +294 -0
- data/_sass/bootstrap/_pagination.scss +73 -0
- data/_sass/bootstrap/_popover.scss +171 -0
- data/_sass/bootstrap/_print.scss +141 -0
- data/_sass/bootstrap/_progress.scss +43 -0
- data/_sass/bootstrap/_reboot.scss +483 -0
- data/_sass/bootstrap/_root.scss +19 -0
- data/_sass/bootstrap/_spinners.scss +55 -0
- data/_sass/bootstrap/_tables.scss +185 -0
- data/_sass/bootstrap/_toasts.scss +44 -0
- data/_sass/bootstrap/_tooltip.scss +115 -0
- data/_sass/bootstrap/_transitions.scss +20 -0
- data/_sass/bootstrap/_type.scss +125 -0
- data/_sass/bootstrap/_utilities.scss +17 -0
- data/_sass/bootstrap/_variables.scss +1123 -0
- data/_sass/bootstrap/bootstrap-grid.scss +29 -0
- data/_sass/bootstrap/bootstrap-reboot.scss +12 -0
- data/_sass/bootstrap/bootstrap.scss +44 -0
- data/_sass/bootstrap/mixins/_alert.scss +13 -0
- data/_sass/bootstrap/mixins/_background-variant.scss +21 -0
- data/_sass/bootstrap/mixins/_badge.scss +17 -0
- data/_sass/bootstrap/mixins/_border-radius.scss +63 -0
- data/_sass/bootstrap/mixins/_box-shadow.scss +20 -0
- data/_sass/bootstrap/mixins/_breakpoints.scss +123 -0
- data/_sass/bootstrap/mixins/_buttons.scss +107 -0
- data/_sass/bootstrap/mixins/_caret.scss +62 -0
- data/_sass/bootstrap/mixins/_clearfix.scss +7 -0
- data/_sass/bootstrap/mixins/_deprecate.scss +10 -0
- data/_sass/bootstrap/mixins/_float.scss +14 -0
- data/_sass/bootstrap/mixins/_forms.scss +192 -0
- data/_sass/bootstrap/mixins/_gradients.scss +45 -0
- data/_sass/bootstrap/mixins/_grid-framework.scss +66 -0
- data/_sass/bootstrap/mixins/_grid.scss +51 -0
- data/_sass/bootstrap/mixins/_hover.scss +37 -0
- data/_sass/bootstrap/mixins/_image.scss +36 -0
- data/_sass/bootstrap/mixins/_list-group.scss +21 -0
- data/_sass/bootstrap/mixins/_lists.scss +7 -0
- data/_sass/bootstrap/mixins/_nav-divider.scss +10 -0
- data/_sass/bootstrap/mixins/_pagination.scss +22 -0
- data/_sass/bootstrap/mixins/_reset-text.scss +17 -0
- data/_sass/bootstrap/mixins/_resize.scss +6 -0
- data/_sass/bootstrap/mixins/_screen-reader.scss +33 -0
- data/_sass/bootstrap/mixins/_size.scss +7 -0
- data/_sass/bootstrap/mixins/_table-row.scss +39 -0
- data/_sass/bootstrap/mixins/_text-emphasis.scss +16 -0
- data/_sass/bootstrap/mixins/_text-hide.scss +11 -0
- data/_sass/bootstrap/mixins/_text-truncate.scss +8 -0
- data/_sass/bootstrap/mixins/_transition.scss +16 -0
- data/_sass/bootstrap/mixins/_visibility.scss +8 -0
- data/_sass/bootstrap/utilities/_align.scss +8 -0
- data/_sass/bootstrap/utilities/_background.scss +19 -0
- data/_sass/bootstrap/utilities/_borders.scss +75 -0
- data/_sass/bootstrap/utilities/_clearfix.scss +3 -0
- data/_sass/bootstrap/utilities/_display.scss +26 -0
- data/_sass/bootstrap/utilities/_embed.scss +39 -0
- data/_sass/bootstrap/utilities/_flex.scss +51 -0
- data/_sass/bootstrap/utilities/_float.scss +11 -0
- data/_sass/bootstrap/utilities/_overflow.scss +5 -0
- data/_sass/bootstrap/utilities/_position.scss +32 -0
- data/_sass/bootstrap/utilities/_screenreaders.scss +11 -0
- data/_sass/bootstrap/utilities/_shadows.scss +6 -0
- data/_sass/bootstrap/utilities/_sizing.scss +20 -0
- data/_sass/bootstrap/utilities/_spacing.scss +73 -0
- data/_sass/bootstrap/utilities/_stretched-link.scss +19 -0
- data/_sass/bootstrap/utilities/_text.scss +72 -0
- data/_sass/bootstrap/utilities/_visibility.scss +13 -0
- data/_sass/bootstrap/vendor/_rfs.scss +204 -0
- data/assets/css/asciidocsy.scss +9 -0
- data/assets/css/asciidoctor.css +776 -0
- data/assets/css/bootstrap-toc.css +60 -0
- data/assets/css/bootstrap.scss +4 -0
- data/assets/css/custom.css +2 -0
- data/assets/css/font-awesome.css +2337 -0
- data/assets/css/font-awesome.min.css +4 -0
- data/assets/css/jquery.navgoco.css +69 -0
- data/assets/css/palette.css +217 -0
- data/assets/css/skins/colony.css +734 -0
- data/assets/css/skins/foundation-lime.css +727 -0
- data/assets/css/skins/foundation-potion.css +727 -0
- data/assets/css/skins/foundation.css +720 -0
- data/assets/css/skins/github.css +741 -0
- data/assets/css/skins/golo.css +738 -0
- data/assets/css/skins/iconic.css +762 -0
- data/assets/css/skins/maker.css +738 -0
- data/assets/css/skins/readthedocs.css +739 -0
- data/assets/css/skins/riak.css +759 -0
- data/assets/css/skins/rocket-panda.css +734 -0
- data/assets/css/skins/rubygems.css +722 -0
- data/assets/css/syntax/hljs/a11y-dark.css +99 -0
- data/assets/css/syntax/hljs/a11y-light.css +99 -0
- data/assets/css/syntax/hljs/agate.css +108 -0
- data/assets/css/syntax/hljs/an-old-hope.css +89 -0
- data/assets/css/syntax/hljs/androidstudio.css +66 -0
- data/assets/css/syntax/hljs/arduino-light.css +87 -0
- data/assets/css/syntax/hljs/arta.css +73 -0
- data/assets/css/syntax/hljs/ascetic.css +45 -0
- data/assets/css/syntax/hljs/atelier-cave-dark.css +83 -0
- data/assets/css/syntax/hljs/atelier-cave-light.css +85 -0
- data/assets/css/syntax/hljs/atelier-dune-dark.css +69 -0
- data/assets/css/syntax/hljs/atelier-dune-light.css +69 -0
- data/assets/css/syntax/hljs/atelier-estuary-dark.css +84 -0
- data/assets/css/syntax/hljs/atelier-estuary-light.css +84 -0
- data/assets/css/syntax/hljs/atelier-forest-dark.css +69 -0
- data/assets/css/syntax/hljs/atelier-forest-light.css +69 -0
- data/assets/css/syntax/hljs/atelier-heath-dark.css +69 -0
- data/assets/css/syntax/hljs/atelier-heath-light.css +69 -0
- data/assets/css/syntax/hljs/atelier-lakeside-dark.css +69 -0
- data/assets/css/syntax/hljs/atelier-lakeside-light.css +69 -0
- data/assets/css/syntax/hljs/atelier-plateau-dark.css +84 -0
- data/assets/css/syntax/hljs/atelier-plateau-light.css +84 -0
- data/assets/css/syntax/hljs/atelier-savanna-dark.css +84 -0
- data/assets/css/syntax/hljs/atelier-savanna-light.css +84 -0
- data/assets/css/syntax/hljs/atelier-seaside-dark.css +69 -0
- data/assets/css/syntax/hljs/atelier-seaside-light.css +69 -0
- data/assets/css/syntax/hljs/atelier-sulphurpool-dark.css +69 -0
- data/assets/css/syntax/hljs/atelier-sulphurpool-light.css +69 -0
- data/assets/css/syntax/hljs/atom-one-dark-reasonable.css +75 -0
- data/assets/css/syntax/hljs/atom-one-dark.css +96 -0
- data/assets/css/syntax/hljs/atom-one-light.css +96 -0
- data/assets/css/syntax/hljs/brown-paper.css +64 -0
- data/assets/css/syntax/hljs/brown-papersq.png +0 -0
- data/assets/css/syntax/hljs/codepen-embed.css +60 -0
- data/assets/css/syntax/hljs/color-brewer.css +71 -0
- data/assets/css/syntax/hljs/darcula.css +74 -0
- data/assets/css/syntax/hljs/dark.css +63 -0
- data/assets/css/syntax/hljs/default.css +99 -0
- data/assets/css/syntax/hljs/docco.css +97 -0
- data/assets/css/syntax/hljs/dracula.css +76 -0
- data/assets/css/syntax/hljs/far.css +71 -0
- data/assets/css/syntax/hljs/foundation.css +89 -0
- data/assets/css/syntax/hljs/github-gist.css +79 -0
- data/assets/css/syntax/hljs/github.css +99 -0
- data/assets/css/syntax/hljs/gml.css +78 -0
- data/assets/css/syntax/hljs/googlecode.css +89 -0
- data/assets/css/syntax/hljs/gradient-dark.css +122 -0
- data/assets/css/syntax/hljs/gradient-light.css +130 -0
- data/assets/css/syntax/hljs/grayscale.css +101 -0
- data/assets/css/syntax/hljs/gruvbox-dark.css +108 -0
- data/assets/css/syntax/hljs/gruvbox-light.css +108 -0
- data/assets/css/syntax/hljs/hopscotch.css +84 -0
- data/assets/css/syntax/hljs/hybrid.css +102 -0
- data/assets/css/syntax/hljs/idea.css +97 -0
- data/assets/css/syntax/hljs/ir-black.css +73 -0
- data/assets/css/syntax/hljs/isbl-editor-dark.css +112 -0
- data/assets/css/syntax/hljs/isbl-editor-light.css +111 -0
- data/assets/css/syntax/hljs/kimbie.dark.css +74 -0
- data/assets/css/syntax/hljs/kimbie.light.css +74 -0
- data/assets/css/syntax/hljs/lightfair.css +88 -0
- data/assets/css/syntax/hljs/lioshi.css +88 -0
- data/assets/css/syntax/hljs/magula.css +70 -0
- data/assets/css/syntax/hljs/mono-blue.css +56 -0
- data/assets/css/syntax/hljs/monokai-sublime.css +83 -0
- data/assets/css/syntax/hljs/monokai.css +71 -0
- data/assets/css/syntax/hljs/night-owl.css +182 -0
- data/assets/css/syntax/hljs/nnfx-dark.css +106 -0
- data/assets/css/syntax/hljs/nnfx.css +106 -0
- data/assets/css/syntax/hljs/nord.css +309 -0
- data/assets/css/syntax/hljs/obsidian.css +88 -0
- data/assets/css/syntax/hljs/ocean.css +74 -0
- data/assets/css/syntax/hljs/paraiso-dark.css +72 -0
- data/assets/css/syntax/hljs/paraiso-light.css +72 -0
- data/assets/css/syntax/hljs/pojoaque.css +83 -0
- data/assets/css/syntax/hljs/pojoaque.jpg +0 -0
- data/assets/css/syntax/hljs/purebasic.css +96 -0
- data/assets/css/syntax/hljs/qtcreator_dark.css +83 -0
- data/assets/css/syntax/hljs/qtcreator_light.css +83 -0
- data/assets/css/syntax/hljs/railscasts.css +106 -0
- data/assets/css/syntax/hljs/rainbow.css +85 -0
- data/assets/css/syntax/hljs/routeros.css +108 -0
- data/assets/css/syntax/hljs/school-book.css +69 -0
- data/assets/css/syntax/hljs/school-book.png +0 -0
- data/assets/css/syntax/hljs/shades-of-purple.css +96 -0
- data/assets/css/syntax/hljs/solarized-dark.css +84 -0
- data/assets/css/syntax/hljs/solarized-light.css +84 -0
- data/assets/css/syntax/hljs/srcery.css +78 -0
- data/assets/css/syntax/hljs/stackoverflow-dark.css +78 -0
- data/assets/css/syntax/hljs/stackoverflow-light.css +78 -0
- data/assets/css/syntax/hljs/sunburst.css +102 -0
- data/assets/css/syntax/hljs/tomorrow-night-blue.css +75 -0
- data/assets/css/syntax/hljs/tomorrow-night-bright.css +74 -0
- data/assets/css/syntax/hljs/tomorrow-night-eighties.css +74 -0
- data/assets/css/syntax/hljs/tomorrow-night.css +75 -0
- data/assets/css/syntax/hljs/tomorrow.css +72 -0
- data/assets/css/syntax/hljs/vs.css +68 -0
- data/assets/css/syntax/hljs/vs2015.css +115 -0
- data/assets/css/syntax/hljs/xcode.css +104 -0
- data/assets/css/syntax/hljs/xt256.css +92 -0
- data/assets/css/syntax/hljs/zenburn.css +80 -0
- data/assets/fonts/FontAwesome.otf +0 -0
- data/assets/fonts/fontawesome-webfont.eot +0 -0
- data/assets/fonts/fontawesome-webfont.svg +2671 -0
- data/assets/fonts/fontawesome-webfont.ttf +0 -0
- data/assets/fonts/fontawesome-webfont.woff +0 -0
- data/assets/fonts/fontawesome-webfont.woff2 +0 -0
- data/assets/images/asciidocsy-nav-model.png +0 -0
- data/assets/images/asciidocsy-screenshot.png +0 -0
- data/assets/images/docops-labs-logo.png +0 -0
- data/assets/images/favicons/favicon-16x16.png +0 -0
- data/assets/images/favicons/favicon-32x32.png +0 -0
- data/assets/images/favicons/favicon.ico +0 -0
- data/assets/images/github-repo-download_screenshot.png +0 -0
- data/assets/images/logo-full.png +0 -0
- data/assets/images/logo.png +0 -0
- data/assets/images/logo.svg +87 -0
- data/assets/images/search-by-algolia-light-background.svg +1 -0
- data/assets/images/thumb-topic-data-source-edit.png +0 -0
- data/assets/js/anchor.min.js +9 -0
- data/assets/js/asciidoctor.min.js +1472 -0
- data/assets/js/bootstrap-toc.js +180 -0
- data/assets/js/bootstrap.min.js +7 -0
- data/assets/js/highlight.pack.js +870 -0
- data/assets/js/jquery-3.3.1.js +10364 -0
- data/assets/js/jquery-3.3.1.min.js +2 -0
- data/assets/js/jquery.cookie.js +114 -0
- data/assets/js/jquery.navgoco.js +314 -0
- data/assets/js/semantics.js +58 -0
- data/assets/js/tabber.js +111 -0
- data/assets/js/tail.js +37 -0
- data/assets/js/toggler.js +50 -0
- data/lib/asciidocsy/data/dependencies.yml +142 -0
- data/lib/asciidocsy/data/releases.yml +245 -0
- data/lib/asciidocsy/templates/notice-file.txt +16 -0
- data/lib/asciidocsy/version.rb +13 -0
- data/lib/asciidocsy.rb +1 -0
- metadata +462 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/switchers
|
|
2
|
+
:page-switcher: user-os
|
|
3
|
+
= Configure Content Switchers
|
|
4
|
+
|
|
5
|
+
Content switchers are a means of showing and hiding specific content on a page.
|
|
6
|
+
The content being switched can come in groups (where switching one _on_ turns others _off_), or a switcher can perform a single show/hide toggle of a group of content.
|
|
7
|
+
|
|
8
|
+
== Example Switcher
|
|
9
|
+
|
|
10
|
+
The next line is rendered differently depending on which button is selected in the page's *switcher to the right*.
|
|
11
|
+
|
|
12
|
+
[.os-win]
|
|
13
|
+
--
|
|
14
|
+
This content is for Windows Only.
|
|
15
|
+
--
|
|
16
|
+
|
|
17
|
+
[.os-nix]
|
|
18
|
+
--
|
|
19
|
+
This content is for Linux Only.
|
|
20
|
+
--
|
|
21
|
+
|
|
22
|
+
[.os-mac]
|
|
23
|
+
--
|
|
24
|
+
This content is for MacOS Only.
|
|
25
|
+
--
|
|
26
|
+
|
|
27
|
+
Switching can even happen inline, with a term like [.os-win]*Microsoft* [.os-mac]*Apple* [.os-nix]*open source*.
|
|
28
|
+
|
|
29
|
+
== Use Cases
|
|
30
|
+
|
|
31
|
+
Aside from enabling users to choose their platform, as with operating systems in the above example, switchers can be used for for [.term]*patch-revision handling*.
|
|
32
|
+
|
|
33
|
+
== Toggle Configuration
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/tabber
|
|
2
|
+
:tab-table-options: frame=none,cols=1a,caption=''
|
|
3
|
+
= Configure Content Tabbers
|
|
4
|
+
|
|
5
|
+
[.tabber-panel.tabs-data-format]
|
|
6
|
+
--
|
|
7
|
+
[.tabber-item.tab-data-yaml,{tab-table-options},title='YAML']
|
|
8
|
+
|===
|
|
9
|
+
|
|
|
10
|
+
[source,YAML]
|
|
11
|
+
----
|
|
12
|
+
some: yaml-data
|
|
13
|
+
goes: here
|
|
14
|
+
----
|
|
15
|
+
|===
|
|
16
|
+
|
|
17
|
+
[.tabber-item.tab-data-json,{tab-table-options},title='JSON']
|
|
18
|
+
|===
|
|
19
|
+
|
|
|
20
|
+
[source,JSON]
|
|
21
|
+
----
|
|
22
|
+
{
|
|
23
|
+
"some": "yaml-data",
|
|
24
|
+
"goes": "here"
|
|
25
|
+
}
|
|
26
|
+
----
|
|
27
|
+
|===
|
|
28
|
+
--
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
[.tabber-panel]
|
|
33
|
+
--
|
|
34
|
+
[.tab-item.Some_Tab_Class]
|
|
35
|
+
====
|
|
36
|
+
Content.
|
|
37
|
+
|
|
38
|
+
Content.
|
|
39
|
+
|
|
40
|
+
More content.
|
|
41
|
+
====
|
|
42
|
+
|
|
43
|
+
[.tab-item.Another_Tab_Class]
|
|
44
|
+
====
|
|
45
|
+
MORE CONTENT
|
|
46
|
+
|
|
47
|
+
And more and more.
|
|
48
|
+
====
|
|
49
|
+
--
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/toggles
|
|
2
|
+
:page-togglers: user-os
|
|
3
|
+
= Configure Content Toggles
|
|
4
|
+
|
|
5
|
+
Some of the content on this page will be hideable when rendered in the Jekyll site.
|
|
6
|
+
|
|
7
|
+
[.os-win]
|
|
8
|
+
--
|
|
9
|
+
This content is for Windows Only.
|
|
10
|
+
--
|
|
11
|
+
|
|
12
|
+
[.os-nix]
|
|
13
|
+
--
|
|
14
|
+
This content is for Linux Only.
|
|
15
|
+
--
|
|
16
|
+
|
|
17
|
+
[.os-mac]
|
|
18
|
+
--
|
|
19
|
+
This content is for MacOS Only.
|
|
20
|
+
--
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/versioning/amenders
|
|
2
|
+
= DOM Amenders
|
|
3
|
+
|
|
4
|
+
By far the most open-ended of the superficial version handlers, DOM amenders enable you to manipulate the DOM in one simple way at a time.
|
|
5
|
+
Not a wide-open API like jQuery itself, but a simple way to execute a jQuery function on the `change()` event.
|
|
6
|
+
|
|
7
|
+
Use cases include switching URLs or switching CSS files in the HTML `<head>`.
|
|
8
|
+
|
|
9
|
+
== Configuring a DOM Amender
|
|
10
|
+
|
|
11
|
+
To create a straightforward amender, make an entry in `site.features.versioning` and give it a [.param]`verb: amend` property.
|
|
12
|
+
The key property for an amender is the `func:` object.
|
|
13
|
+
This property must contain the `name:` of a <<built-in-amenders,built-in function>> or a `file:` to designate a <<custom-amender,custom JavaScript snippet>>.
|
|
14
|
+
|
|
15
|
+
[[built-in-amenders]]
|
|
16
|
+
=== Built-in Amender Functions
|
|
17
|
+
|
|
18
|
+
The existing named functions are:
|
|
19
|
+
|
|
20
|
+
change-url::
|
|
21
|
+
Alters the browser location.
|
|
22
|
+
Requires the `href:` property for passing a URL to which to send the browser.
|
|
23
|
+
|
|
24
|
+
change-href::
|
|
25
|
+
Alters the path of a resource file's source.
|
|
26
|
+
Requires an element to target (`targ:`) and a URL path to replace the token with.
|
|
27
|
+
|
|
28
|
+
The `href:` property in a built-in function can include Liquid syntax as well as JavaScript syntax.
|
|
29
|
+
Liquid will be executed at build-time; JavaScript will be executed in the browser.
|
|
30
|
+
|
|
31
|
+
Here is the source of the syntax skin changer in the right-hand sidebar.
|
|
32
|
+
|
|
33
|
+
[source,yaml]
|
|
34
|
+
----
|
|
35
|
+
include::_data/theme/versioning.yml[tags=syntax-skin-amend]
|
|
36
|
+
----
|
|
37
|
+
|
|
38
|
+
<1> The `targ:` property accepts a String in the form of a link:https://api.jquery.com/category/selectors/[jQuery selector] determining the element to act upon.
|
|
39
|
+
|
|
40
|
+
<2> The syntax `>-` designates that the String value should be trimmed of internal newlines and surrounding whitespace.
|
|
41
|
+
This is helpful when passing Liquid or other syntax intended for rendering inline.
|
|
42
|
+
|
|
43
|
+
[[custom-amender]]
|
|
44
|
+
=== Your Own DOM Amender Function
|
|
45
|
+
|
|
46
|
+
AsciiDocsy provides two key components to establish this functionality.
|
|
47
|
+
The first is the *formfield elements* populated by an array and defined by other settings, as with other version handlers.
|
|
48
|
+
|
|
49
|
+
The *version-handler.html* partial can generate generate either a `select` dropdown or radio `buttons`.
|
|
50
|
+
Pass it an [.term]*array* of [.term.scalar]*scalars* to establish the displayed option and the underlying value as one and the same.
|
|
51
|
+
Pass an array of dictionary objects bearing `text` and `slug` properties, and it will use these values for the option _labels_ and _values_, respectively.
|
|
52
|
+
|
|
53
|
+
To register your own DOM amender, add a template file (`.html` or `.js`) to the `_includes/` directory, and register it as the `func.file:` value inside your amender block.
|
|
54
|
+
|
|
55
|
+
.Example custom amender definition
|
|
56
|
+
[source,yaml]
|
|
57
|
+
----
|
|
58
|
+
versioning:
|
|
59
|
+
...
|
|
60
|
+
my-amender:
|
|
61
|
+
verb: amend
|
|
62
|
+
form: select
|
|
63
|
+
func:
|
|
64
|
+
file: my-amender.js
|
|
65
|
+
swap:
|
|
66
|
+
data: site.data.my-array
|
|
67
|
+
pick: some-value
|
|
68
|
+
----
|
|
69
|
+
|
|
70
|
+
Your handler will be interpreted by `_includes/versioning-controls.html` and the controller will be generated by `_includes/version-handlers.html`.
|
|
71
|
+
|
|
72
|
+
It is called from within a `$(function(){` call that executes as the page loads.
|
|
73
|
+
|
|
74
|
+
[NOTE]
|
|
75
|
+
This functionality is likely to change by AsciiDocsy v1.0.
|
|
76
|
+
The JS will be captured inline and expressed in the tail of the document to move it out of the HTML.
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/versioning/swaps
|
|
2
|
+
:theme: <$tok.theme>
|
|
3
|
+
:company: <$tok.company>
|
|
4
|
+
:company_url: <$tok.company_url>
|
|
5
|
+
:product_vrsn: 1.2.1
|
|
6
|
+
:vrsn: <$tok.vrsn>
|
|
7
|
+
:page-version-handlers: +user-os-toggle,+spoof-tokens-swap,+patch-swap-0_2,+user-os-swap
|
|
8
|
+
= Token Swaps
|
|
9
|
+
|
|
10
|
+
Token swaps enable you to place what I call "`front-end variables`" in your AsciiDoc or other page elements that can be altered either by an act of the user or a URL query string.
|
|
11
|
+
Use this method to reduce the number of builds you perform just to alter small bits of text.
|
|
12
|
+
|
|
13
|
+
Once a user makes a selection (or has been directed to a specific URL), the swaps remain in play for the duration of their session.
|
|
14
|
+
|
|
15
|
+
== Swap Configuration
|
|
16
|
+
|
|
17
|
+
Like other handlers, swaps are defined in the `versioning` data object.
|
|
18
|
+
Name a swap object whatever you wish, and then give it the property [.param]`verb: swap`.
|
|
19
|
+
|
|
20
|
+
A swap can be triggered by a `select` dropdown or radio `buttons`.
|
|
21
|
+
|
|
22
|
+
Swaps can have a `dict:` property that establishes default tokens.
|
|
23
|
+
They must have an `swap.opts:` property that defines the "`slates`" of tokens.
|
|
24
|
+
These slates are what is being chosen during a swap.
|
|
25
|
+
|
|
26
|
+
[IMPORTANT]
|
|
27
|
+
Even though tokens are broken down to separate dicts and slates, _tokens must be unique across all dictionaries_.
|
|
28
|
+
At expression time, swaps alter the value of _every_ token bearing that slug.
|
|
29
|
+
|
|
30
|
+
== Token Expression
|
|
31
|
+
|
|
32
|
+
To express a token inside AsciiDoc text, use one of the following methods.
|
|
33
|
+
|
|
34
|
+
inline role::
|
|
35
|
+
This option uses AsciiDoc's inline semantics to wrap text in a `.tok` class with a secondary class matching the slug of the token.
|
|
36
|
+
For example, `+++[.tok.token_name]#Default Text#+++` declares that we want to offer a token for swapping, and it is named `token_name` and has an inline default set as `Default Text`.
|
|
37
|
+
|
|
38
|
+
hard token::
|
|
39
|
+
As an alternative that is easy to store in an AsciiDoc attribute (see <<attribute-tokens>> below), use a token formatted like so: `<$tok.token_name>`.
|
|
40
|
+
Replace `token_name` with the slug value for your token.
|
|
41
|
+
There is no option for default text at this time.
|
|
42
|
+
|
|
43
|
+
== Examples
|
|
44
|
+
|
|
45
|
+
It's probably best to start showing you some swaps.
|
|
46
|
+
|
|
47
|
+
=== Patch Version Switcher
|
|
48
|
+
|
|
49
|
+
We will start with a simple example, and likely the most common implementation: a patch-version switcher.
|
|
50
|
+
If the only thing that changes in your docs between patch versions is the patch version itself, use this trick to let users choose the precise product version they are using or installing without changing pages (and without duplicate builds).
|
|
51
|
+
|
|
52
|
+
On the right-hand sidebar, there is a selectbox labeled [.gui]*Select your patch version:*.
|
|
53
|
+
|
|
54
|
+
Watch what happens to this text (*<$tok.vrsn>*) when you change the patch version, sourced as [.code.nosub]`<$tok.vrsn>`.
|
|
55
|
+
|
|
56
|
+
And here is another version ([.tok.vrsn]*0.2.0*) sourced differently ([.code.nosub]`+++[.tok.vrsn]*0.2.0*+++`).
|
|
57
|
+
|
|
58
|
+
This set of swaps is registered as a version handler.
|
|
59
|
+
|
|
60
|
+
[source,yaml]
|
|
61
|
+
----
|
|
62
|
+
features:
|
|
63
|
+
actions:
|
|
64
|
+
versioning:
|
|
65
|
+
...
|
|
66
|
+
patch-swap-0_2:
|
|
67
|
+
include::_data/theme/versioning.yml[tags="sample-swap-patch"]
|
|
68
|
+
----
|
|
69
|
+
|
|
70
|
+
In this example, the swap pivots on a single token and a single set of values.
|
|
71
|
+
|
|
72
|
+
<1> The `slug:` property names the token.
|
|
73
|
+
<2> The `opts:` property in this case is a simple array of scalars.
|
|
74
|
+
|
|
75
|
+
=== Token Slates
|
|
76
|
+
|
|
77
|
+
A swap handler will alter every instance of a token on a page at once, but if you want a handler to swap (every instance of) multiple different tokens, you'll need some dictionaries.
|
|
78
|
+
|
|
79
|
+
Let's say I wanted to distribute two more editions of AsciiDocsy: "`freemium`" platform and a commercial version, in addition to the free and open-source version.
|
|
80
|
+
Obviously these docs would be largely identical to the free version, but they might have some different contents.
|
|
81
|
+
|
|
82
|
+
First we need to define tokens for swapping.
|
|
83
|
+
Let's go with `theme`, `company`, and `company_url`, which will have different values given different slates (listed under the `opts:` property).
|
|
84
|
+
|
|
85
|
+
.Defining a swap dictionary
|
|
86
|
+
[source,yaml]
|
|
87
|
+
----
|
|
88
|
+
features:
|
|
89
|
+
actions:
|
|
90
|
+
versioning:
|
|
91
|
+
...
|
|
92
|
+
theme-name-tokens:
|
|
93
|
+
include::_data/theme/versioning.yml[tags="sample-swap-spoof"]
|
|
94
|
+
----
|
|
95
|
+
|
|
96
|
+
The top-level `dict:` [.out]#2# object defines the default dictionary.
|
|
97
|
+
Thereafter, slates (items in `opts:` [.out]#2#) can override the defaults as needed using a nested `dict:` [.out]#3# (x2) property of their own.
|
|
98
|
+
|
|
99
|
+
Here we see the first slate (`foss`) simply uses the default dictionary while each of the next two define overrides.
|
|
100
|
+
|
|
101
|
+
Now that our tokens are defined, we can start placing them inside our AsciiDoc content.
|
|
102
|
+
|
|
103
|
+
[source,asciidoc,subs=none,role=nosub]
|
|
104
|
+
----
|
|
105
|
+
The <$tok.theme> theme, brought to you by <$tok.company> (link:<$tok.company_url>[website]), is really awesome.
|
|
106
|
+
|
|
107
|
+
The company slogan is <$tok.slogan>.
|
|
108
|
+
----
|
|
109
|
+
|
|
110
|
+
[NOTE.limit]
|
|
111
|
+
Limitation: As you can see in the above example, token swaps inside HTML element attributes (such as `href` here) are not yet working.
|
|
112
|
+
|
|
113
|
+
.Renders
|
|
114
|
+
====
|
|
115
|
+
The <$tok.theme> theme, brought to you by <$tok.company> (link:<$tok.company_url>[website]), is really awesome.
|
|
116
|
+
|
|
117
|
+
The company slogan is <$tok.slogan>.
|
|
118
|
+
====
|
|
119
|
+
|
|
120
|
+
[[attribute-tokens]]
|
|
121
|
+
=== Storing Tokens as AsciiDoc Attributes
|
|
122
|
+
|
|
123
|
+
Placing AsciiDocsy swap tokens directly in AsciiDoc syntax does not carry over to non-AsciiDocsy output.
|
|
124
|
+
For this and other reasons, the preferred way to handle swap tokens is by defining them with AsciiDoc attributes.
|
|
125
|
+
|
|
126
|
+
Provide different values to all your way you can override the token syntax with an explicit value anytime you wish at build-time.
|
|
127
|
+
|
|
128
|
+
This method easier to manage and looks nicer on the page, as well.
|
|
129
|
+
|
|
130
|
+
:theme_slug: AsciiDocsy
|
|
131
|
+
:company_slug: DocOps.Lab
|
|
132
|
+
:theme: AsciiDocsy
|
|
133
|
+
:company: DocOps.Lab
|
|
134
|
+
|
|
135
|
+
.Example: hard tokens stored as attributes
|
|
136
|
+
[source,asciidoc,subs=none,role=nosub]
|
|
137
|
+
----
|
|
138
|
+
The [.tok.theme]#{theme}# theme, brought to you by [.tok.company]#{company}# (link:{company_url}[[website]), is really awesome.
|
|
139
|
+
----
|
|
140
|
+
|
|
141
|
+
.Renders
|
|
142
|
+
====
|
|
143
|
+
The {theme} theme, brought to you by {company} (link:{company_url}[website]), is really awesome.
|
|
144
|
+
====
|
|
145
|
+
|
|
146
|
+
Without storing your tokens as attributes, you are stuck with those tokens in alternative formats that lack frontend manipulation via JavaScript, such as PDF.
|
|
147
|
+
|
|
148
|
+
== Toggle Piggy-backing
|
|
149
|
+
|
|
150
|
+
If a swap and a toggle have the same set of options, the swap can piggy-back on the toggle.
|
|
151
|
+
This means the toggle will now perform two actions:
|
|
152
|
+
|
|
153
|
+
. It will _show_ any content bearing the "`role`" class defined for the toggle (while hiding content bearing toggled-off classes).
|
|
154
|
+
. It will also swap any tokens for values assigned to the slate that goes with that role/slug.
|
|
155
|
+
|
|
156
|
+
Let's look at an example.
|
|
157
|
+
|
|
158
|
+
[source,yaml]
|
|
159
|
+
----
|
|
160
|
+
features:
|
|
161
|
+
actions:
|
|
162
|
+
versioning:
|
|
163
|
+
...
|
|
164
|
+
include::_data/theme/versioning.yml[tags="sample-swap-piggyback"]
|
|
165
|
+
----
|
|
166
|
+
|
|
167
|
+
.See the swap in action
|
|
168
|
+
====
|
|
169
|
+
Use the OS selector in the right-hand sidebar to swap slates.
|
|
170
|
+
|
|
171
|
+
your OS::
|
|
172
|
+
[.os-mac]#MacOS# [.os-nix]#Linux/Unix# [.os-win]#Windows#
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
something about your technology::
|
|
176
|
+
<$tok.your_os>
|
|
177
|
+
|
|
178
|
+
something about you::
|
|
179
|
+
<$tok.you>
|
|
180
|
+
====
|
|
181
|
+
|
|
182
|
+
.Swap source
|
|
183
|
+
[source,asciidoc,role=nosub]
|
|
184
|
+
----
|
|
185
|
+
your OS::
|
|
186
|
+
[.os-mac]#MacOS# [.os-nix]#Linux/Unix# [.os-win]#Windows#
|
|
187
|
+
|
|
188
|
+
something about your technology::
|
|
189
|
+
<$tok.your_os>
|
|
190
|
+
|
|
191
|
+
something about you::
|
|
192
|
+
<$tok.you>
|
|
193
|
+
----
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/versioning/tabsets
|
|
2
|
+
:tab-table-options: frame=none,cols=1a,caption=''
|
|
3
|
+
= Pane Tabs
|
|
4
|
+
|
|
5
|
+
include::{path_to_snippets}/handlers-table.adoc[tags="table-head,table-row-tabsets,table-tail"]
|
|
6
|
+
|
|
7
|
+
The act of using local *tabs* to swap between "`overlapping`" *panes* of content blocks is called "`tabbing panes.`"
|
|
8
|
+
|
|
9
|
+
include::{path_to_snippets}/example_tabset-source.adoc[tags=raw]
|
|
10
|
+
|
|
11
|
+
== Example
|
|
12
|
+
|
|
13
|
+
Take another look at our example tabset.
|
|
14
|
+
|
|
15
|
+
include::{path_to_snippets}/example_tabset-source.adoc[tags=raw]
|
|
16
|
+
|
|
17
|
+
Now, to examine the source.
|
|
18
|
+
You may be surprised to see it is just conventional AsciiDoc.
|
|
19
|
+
|
|
20
|
+
.Source for above tabset
|
|
21
|
+
[source,asciidoc,subs=-quotes]
|
|
22
|
+
--------
|
|
23
|
+
include::{path_to_snippets}/example_tabset-source.adoc[tags=marked]
|
|
24
|
+
--------
|
|
25
|
+
|
|
26
|
+
<1> The whole handler must be wrapped in an [.term.open-block-asciidoc]*AsciiDoc open block* with the `tabber-tabset` role (class) assigned.
|
|
27
|
+
An optional second class names the tabset and _can_ match the name for an optional configuration entry in the version-handlers registry.
|
|
28
|
+
|
|
29
|
+
<2> Inside the open block, we can place any (untested) number of content panes, which can take the form of nearly any block element, such as code listings, example blocks, or tables.
|
|
30
|
+
They need only be assigned the `tabber-pane` role (class) and a class that matches `pane-<option-slug>`.
|
|
31
|
+
In the case that you have registered an `opts` block in the optional config for this tabset, the `<option-slug>` must match the slug for the registered option to make use of its metadata.
|
|
32
|
+
+
|
|
33
|
+
[NOTE]
|
|
34
|
+
Due to a limitation in AsciiDoc, the outer open block cannot include another open block -- there is no syntax for it as of Asciidoctor 2.
|
|
35
|
+
To create a truly transparent content block, try including a table with no borders.
|
|
36
|
+
The `+++{tab-table-options}+++` attribute is set to: `{tab-table-options}`.
|
|
37
|
+
|
|
38
|
+
<3> The second tab's definition in this case includes an explicit `title` argument, which overrides the `text` label assigned in the registry.
|
|
39
|
+
|
|
40
|
+
=== Customizations
|
|
41
|
+
|
|
42
|
+
include::{path_to_snippets}/example_tabset-source.adoc[tags=xml-raw]
|
|
43
|
+
|
|
44
|
+
Now, to examine the source.
|
|
45
|
+
You may be surprised to see it is just conventional AsciiDoc.
|
|
46
|
+
|
|
47
|
+
.Source for above tabset
|
|
48
|
+
[source,asciidoc]
|
|
49
|
+
--------
|
|
50
|
+
include::{path_to_snippets}/example_tabset-source.adoc[tags=xml-marked]
|
|
51
|
+
--------
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/versioning/toggles
|
|
2
|
+
:page-version-handlers: +user-os-toggle,-theme-skin-amend,-syntax-skin-amend
|
|
3
|
+
= Class Toggles
|
|
4
|
+
|
|
5
|
+
include::{path_to_snippets}/handlers-table.adoc[tags="table-head,table-row-toggles,table-tail"]
|
|
6
|
+
|
|
7
|
+
This handler enables switching the show/hide states of elements assigned certain classes.
|
|
8
|
+
A classic use case showing different content in the same page depending on the user's operating system.
|
|
9
|
+
|
|
10
|
+
With AsciiDocsy class toggles, this choice follows the user throughout the site.
|
|
11
|
+
You can essentially embed multiple user experiences right into the same pages of your site, assuming the divergence is not too drastic.
|
|
12
|
+
|
|
13
|
+
== Implementation
|
|
14
|
+
|
|
15
|
+
Class toggles must be registered in the `versioning:` data object.
|
|
16
|
+
Create a new block with an arbitrary name, optionally including `-toggle` to help keep track.
|
|
17
|
+
Add a required block called `swap:`, under which options can be derived from a `data:` file or from an explicit `opts:` list.
|
|
18
|
+
|
|
19
|
+
The rest of the implementation process involves adding classes to blocks or segments of text.
|
|
20
|
+
Use inline role syntax to designate a chunk of text as belonging to one or another class.
|
|
21
|
+
|
|
22
|
+
To toggle an entire section, add a class to the heading and group the rest in an [.term.open-block-asciidoc]*open block*, then assign a class to it.
|
|
23
|
+
|
|
24
|
+
== Example
|
|
25
|
+
|
|
26
|
+
The following content is applicable to only one or two operating systems at a time.
|
|
27
|
+
|
|
28
|
+
.Example content (paragraph blocks) bearing registered classes
|
|
29
|
+
====
|
|
30
|
+
include::{path_to_snippets}/example_toggles.adoc[tags=user-os]
|
|
31
|
+
====
|
|
32
|
+
|
|
33
|
+
The markup behind that content can be readily distinguished and edited.
|
|
34
|
+
|
|
35
|
+
.AsciiDoc source for above example
|
|
36
|
+
[source,asciidoc,subs=none]
|
|
37
|
+
----
|
|
38
|
+
include::{path_to_snippets}/example_toggles.adoc[tags=user-os]
|
|
39
|
+
----
|
|
40
|
+
|
|
41
|
+
Class toggling can be performed on inline text elements, as well, but if you plan to do this heavily, you may find it handier to use token swaps in most such cases.
|
|
42
|
+
To expand the power/precision of your toggles, consider adding a swap slate and then <</docs/theme/config/versioning/swaps#toggle-piggy-backing,piggybacking that swap onto your toggle>>.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
:page-permalink: /docs/theme/config/versioning
|
|
2
|
+
:tab-table-options: frame=none,cols=1a,caption=''
|
|
3
|
+
:page-version-handlers: +user-os-toggle,+patch-swap-0_2-btns,+user-os-swap
|
|
4
|
+
= Version Handlers
|
|
5
|
+
|
|
6
|
+
Version handlers are front-end features that enable site users to see only the content that applies to their product version, role, use case, environment, preference, or other condition.
|
|
7
|
+
You can use version handlers however you want, but we present here some guidance for choosing among the options to suit your application.
|
|
8
|
+
Further topics detail the configuration of each handler type.
|
|
9
|
+
|
|
10
|
+
Handlers are named for their duty, not the form their controllers take.
|
|
11
|
+
The handler types perform distinct actions on the selected jQuery JavaScript `ready`, `change`, `focus`, or similar event.
|
|
12
|
+
|
|
13
|
+
[NOTE]
|
|
14
|
+
You do not need to know JavaScript or jQuery to implement handlers.
|
|
15
|
+
AsciiDocsy pre-customizes and extends Bootstrap features to provide configuration-based adaptation to your use case.
|
|
16
|
+
|
|
17
|
+
The rest of this topic provides an overview of attributes and functions common across version handlers as well as a guide for choosing between the various handler types.
|
|
18
|
+
|
|
19
|
+
== Version Handler Verbs
|
|
20
|
+
|
|
21
|
+
Version handlers are named for _what they do_, not what they look like.
|
|
22
|
+
For instance, the user can _swap_ tokens, _tab_ through a set of content blocks, _toggle_ classes to show/hide, or _amend_ the HTML document object model (DOM).
|
|
23
|
+
These labels are imperfect, but they allow us to distinguish _function_ from _form_.
|
|
24
|
+
|
|
25
|
+
=== _Tab_ Block Content in Place
|
|
26
|
+
|
|
27
|
+
Most common with code listings and log samples, [.case]*_if you need to alternate versions of content inside a fixed block_* without forcing the user to scroll, your optimal solution is *tabbing*.
|
|
28
|
+
|
|
29
|
+
These handlers use JavaScript to glean combinations of selector *tabs* and content *panes* out of the HTML rendered from conventional AsciiDoc syntax.
|
|
30
|
+
|
|
31
|
+
[[data-formats-listing]]
|
|
32
|
+
.Tabbed panes sourced entirely as AsciiDoc
|
|
33
|
+
====
|
|
34
|
+
include::{path_to_snippets}/example_tabset-source.adoc[tags=raw]
|
|
35
|
+
====
|
|
36
|
+
|
|
37
|
+
Any tabset or tab/pane class that is repeated throughout a page (and the rest of the site if cookies are enabled) will pre-select the last-chosen tab until altered by the user.
|
|
38
|
+
|
|
39
|
+
<</docs/theme/config/versioning/tabsets#,Learn more about pane tabs>>.
|
|
40
|
+
|
|
41
|
+
=== _Toggle_ Classes
|
|
42
|
+
|
|
43
|
+
Sometimes you need a combination of tabsets and swaps, [.case]*_alternating and muting larger blocks or shorter strings of text throughout a page_*.
|
|
44
|
+
A *toggle* lets you show elements of one class while hiding the rest of the classes in a group.
|
|
45
|
+
|
|
46
|
+
.Give it a try!
|
|
47
|
+
====
|
|
48
|
+
In the sidebar to your right is a set of buttons labeled with the three most popular families of operating systems.
|
|
49
|
+
|
|
50
|
+
Toggle through them and see the content change here.
|
|
51
|
+
|
|
52
|
+
[horizontal]
|
|
53
|
+
Operating System:: [.os-win]*Windows* [.os-mac]*MacOS* [.os-nix]*Linux*
|
|
54
|
+
Unix-like?:: [.os-win]#False# [.os-mac.os-nix]#True#
|
|
55
|
+
====
|
|
56
|
+
|
|
57
|
+
If inline content or various parts of an entire page need to be customized for user experience, apply classes ("`roles`" in AsciiDoc parlance) to the content.
|
|
58
|
+
|
|
59
|
+
Toggles are centrally defined in the Jekyll config, but you choose which pages the controllers appear on.
|
|
60
|
+
|
|
61
|
+
<</docs/theme/config/versioning/toggles#,Dive deeper into toggles.>>
|
|
62
|
+
|
|
63
|
+
=== _Swap_ Tokens in Place
|
|
64
|
+
|
|
65
|
+
In some cases, [.case]*_one simple string needs to be altered in numerous parts of a page_*, but it makes no sense to generate a whole version of the docs just to display this alternate content.
|
|
66
|
+
A *swap* changes the value of tokenized content throughout the page.
|
|
67
|
+
|
|
68
|
+
This feature is most commonly used to alter patch-revision numbers, such as in product-download paths and installation instructions.
|
|
69
|
+
Drop something like `+++[.tok.vrsn]*0.2.0*+++` into your page, and watch the version change as you switch between versions using the buttons to the right, below the table of contents: [.tok.vrsn]*0.2.0*.
|
|
70
|
+
|
|
71
|
+
Swaps can be user triggered by a radio button set or a selectbox.
|
|
72
|
+
|
|
73
|
+
==== Swap Token Slates
|
|
74
|
+
|
|
75
|
+
[.case]*_If you have more than one string to swap when a version changes_*, use token slates.
|
|
76
|
+
This capability could be invaluable to the process of "`white labeling`" a docset.
|
|
77
|
+
Replace key terms related to your or a customer's company, brand, or specific implementation of your product.
|
|
78
|
+
|
|
79
|
+
Token sets are defined in data files and can be swapped using buttons or selectboxes.
|
|
80
|
+
|
|
81
|
+
<</docs/theme/config/versioning/swaps#,See the swaps configuration page for examples.>>
|
|
82
|
+
|
|
83
|
+
=== _Amend_ URLs, Head Links, Anything in the DOM
|
|
84
|
+
|
|
85
|
+
When you need to go big, *version-dommer.html* is your tool.
|
|
86
|
+
At this time, Dommers can *_target the browser's location (URL) or any element in the current page's HTML5 DOM_*.
|
|
87
|
+
|
|
88
|
+
Taking the form of a selectbox or buttons, amenders are like an open-ended token swapper, targeting any discrete aspect of an HTML element that you can latch onto with jQuery.
|
|
89
|
+
|
|
90
|
+
The AsciiDocsy skin selectors are examples of changers that target CSS link refs in the header.
|
|
91
|
+
If you have not yet played with the theme skin changers that are in the right-hand sidebar throughout this site, select an alternative theme skin and review this same page.
|
|
92
|
+
Alternatively, choose a syntax skin and take another look at our <<data-formats-listing,YAML and JSON data listings>>.
|
|
93
|
+
|
|
94
|
+
These cases alter a CSS filename, but other functions are available.
|
|
95
|
+
Any system that changes URLs between docsets (substantial versioning) would use this handler to bump locations to a parallel revision directory.
|
|
96
|
+
|
|
97
|
+
A DOM amender toggle could also be used to switch between the light and dark themes of a website.
|
|
98
|
+
|
|
99
|
+
<</docs/theme/config/versioning/amenders#,Learn more about customizing DOM amenders.>>
|
|
100
|
+
|
|
101
|
+
== Establishing & Overriding Defaults
|
|
102
|
+
|
|
103
|
+
All version handlers respect the same cascade hierarchy for establishing active options.
|
|
104
|
+
|
|
105
|
+
Every handler plants a cookie on the visiting browser so their choice is recalled for subsequent URLs during the session or until they clear their cookies.
|
|
106
|
+
This cookie becomes the effective, overriding default until another choice is actively made by the user (or a until link sends them to a URL that alters the choice).
|
|
107
|
+
|
|
108
|
+
In their configuration, every handler gets a *`pick:` parameter* to set the base system default.
|
|
109
|
+
If no `pick:` property exists or if the value is not an option, the *first option* will be selected by default.
|
|
110
|
+
|
|
111
|
+
If a *query string parameter* is provided in the URL, it will override any system default or cookie.
|
|
112
|
+
Query strings are formatted as `?<handler-id>=<option-slug>[&<handler-id>=<option-slug>]`.
|
|
113
|
+
|
|
114
|
+
.Try it out!
|
|
115
|
+
====
|
|
116
|
+
Use the following URL to pre-select options on this very page and anywhere else the same set of tab classes is used in the site.
|
|
117
|
+
|
|
118
|
+
link:?user-os-toggle=os-nix&data-format-tabber=data-json[]
|
|
119
|
+
====
|
|
120
|
+
|
|
121
|
+
Any time a *user selects* (or a URL determines) an option, that option becomes active and the cookie is instantly updated.
|
|
122
|
+
|
|
123
|
+
[WARNING]
|
|
124
|
+
If you use `form: none`, no controller will appear to enable users to change versions from within the page, and only a URL change will make or alter a version choice.
|
|
125
|
+
Tempting as this capability may seem, *NOTE* that it is _not_ a secure way to hide information from end users.
|
|
126
|
+
The code decrypted by their browser will contain all of the alternate options they are not seeing on the front end.
|
|
127
|
+
|
|
128
|
+
[NOTE]
|
|
129
|
+
By AsciiDocsy 1.0, an additional means of overriding a default option will include the domain or CNAME (subdomain) that is calling the page, so nothing as obvious as a `?parameter=value` need be used.
|
|
130
|
+
|
|
131
|
+
[[handlers-review]]
|
|
132
|
+
== Version Handlers Review
|
|
133
|
+
|
|
134
|
+
include::{path_to_snippets}/handlers-table.adoc[]
|