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,131 @@
|
|
1
|
+
:page-permalink: /docs/theme/config
|
2
|
+
= Site/Theme Configuration
|
3
|
+
|
4
|
+
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*.
|
5
|
+
|
6
|
+
== Configuration Scopes
|
7
|
+
|
8
|
+
AsciiDocsy makes distinct use of the two global [.term.variable-scope]*variable scopes* provided by Jekyll: `site` and `site.data`.
|
9
|
+
Other than the `site.data` object itself, `site`-scoped variables are sourced in Jekyll configuration files.
|
10
|
+
|
11
|
+
The `site.data` scope, or just "`data scope`", is sourced in the Jekyll data directory.
|
12
|
+
This is conventionally `_data/`, but for the AsciiDocsy docs themselves, it is `_docs/_data/`.
|
13
|
+
The location is established by the `site.data_dir` Jekyll property.
|
14
|
+
|
15
|
+
All objects in both the `site` and `site.data` scopes are available anywhere Jekyll parses Liquid-formatted templates.
|
16
|
+
However, their references (full variable names) are determined differently.
|
17
|
+
|
18
|
+
=== Sourcing & Referencing
|
19
|
+
|
20
|
+
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.
|
21
|
+
|
22
|
+
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.
|
23
|
+
All YAML files consumed as part of the configuration are flattened to the `site` scope.
|
24
|
+
|
25
|
+
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.
|
26
|
+
|
27
|
+
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.
|
28
|
+
So a data object called `myobject` inside a file called `myfile.yml` in the folder `_data/myfolder/` would be `site.data.myfolder.myfile.myobject`.
|
29
|
+
|
30
|
+
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.
|
31
|
+
|
32
|
+
== Site-scoped Configuration
|
33
|
+
|
34
|
+
The `site` scope is used for configuring the Jekyll application itself and Jekyll plugins delivered as Ruby gems -- _other than the AsciiDocsy theme_ itself.
|
35
|
+
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.
|
36
|
+
|
37
|
+
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).
|
38
|
+
|
39
|
+
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.
|
40
|
+
This could also be a base directory like `_configs/`.
|
41
|
+
|
42
|
+
[TIP]
|
43
|
+
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.
|
44
|
+
|
45
|
+
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`.
|
46
|
+
This is for configuring plugins used to index content or distribute analytics to an external provider.
|
47
|
+
|
48
|
+
While Algolia is an official plugin, your Google Analytics JavaScript might not have any back-end component at all.
|
49
|
+
But since site analytics tracking feature have nothing to do with the site theme or the site content, it is a `site`-scoped configuration.
|
50
|
+
Whereas the list fo JavaScript files used by AsciiDocsy is situated in the `site.data.theme` scope, as it is highly theme-specific.
|
51
|
+
|
52
|
+
As you will see, the great bulk of configuration options and other AsciiDocsy goodies are defined in the `data` scope.
|
53
|
+
|
54
|
+
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.
|
55
|
+
|
56
|
+
== Data-scoped Configs & Content
|
57
|
+
|
58
|
+
The `site.data` scope has multiple purposes, including content-related information and further configuration.
|
59
|
+
Established purposes include:
|
60
|
+
|
61
|
+
subject data::
|
62
|
+
Structured information about your product, project, or other subject.
|
63
|
+
Key objects include `site.data.navs`, for defining the information architecture of your site, and `site.data.terms`, for defining a glossary.
|
64
|
+
|
65
|
+
theme data::
|
66
|
+
Objects that define theme-related components, elements, and styles.
|
67
|
+
Theme objects include `site.data.theme.navigation`, `site.data.versioning`, and `page-actions`.
|
68
|
+
|
69
|
+
=== Form/Function vs Content
|
70
|
+
|
71
|
+
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.
|
72
|
+
|
73
|
+
Let's look at an example.
|
74
|
+
As you might expect given their distinctness, the data objects called `nav` and `navigation` each serve a different purpose.
|
75
|
+
|
76
|
+
The data object `nav` actually defines your site's navigation _content_.
|
77
|
+
It's what goes into the navs -- the links and their labels, as well as any nested structuring.
|
78
|
+
|
79
|
+
The `navigation` object, meanwhile, defines various navigation components (menus and link lists), with regard to placement, appearance, and functionality.
|
80
|
+
|
81
|
+
Another example is the two `strings` objects, one directly at `data.strings` and another at `data.theme.strings`.
|
82
|
+
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_.
|
83
|
+
|
84
|
+
*When adding new files*, use this rule of thumb to determine placement.
|
85
|
+
|
86
|
+
* [.case]*If the data modifies the _presentation_ or _functionality_ of an HTML element or the like*, locate it in `data.theme`.
|
87
|
+
|
88
|
+
* [.case]*If the data is content-specific and "`portable`"*, it goes directly in the `data` scope.
|
89
|
+
|
90
|
+
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.
|
91
|
+
|
92
|
+
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.
|
93
|
+
Most version handlers can take data options directly or ingest them from a third source; the latter approach separates form from content.
|
94
|
+
|
95
|
+
=== File Placement
|
96
|
+
|
97
|
+
The dot-delimited reference system allows you to choose the arrangement of your Jekyll application's data files.
|
98
|
+
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.
|
99
|
+
|
100
|
+
For example, the AsciiDocsy docs application uses the path `_docs/_data/theme/versioning.yml` as the home for the `site.theme.versioning` object.
|
101
|
+
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`.
|
102
|
+
|
103
|
+
These objects will always be referenced _in documentation_ using the same dot notation, such as `site.data.theme.versioning.handlers.user-os-swap`.
|
104
|
+
The data object itself could, however, be on either of these paths:
|
105
|
+
|
106
|
+
* `_data/theme/versioning/handlers.yml`
|
107
|
+
* `_data/theme/versioning/handlers/user-os-swap.yml`
|
108
|
+
|
109
|
+
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.
|
110
|
+
Your preferences may vary.
|
111
|
+
|
112
|
+
[NOTE]
|
113
|
+
Liquid markup can reference variables using dot-notation, bracket notation, or a mix.
|
114
|
+
So the above could be `site.data.theme.versioning['handlers']['user-os-swap']`.
|
115
|
+
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`.
|
116
|
+
|
117
|
+
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.
|
118
|
+
|
119
|
+
See the <</docs/theme/config/api-reference#,Theme Configuration API Reference>> for all available objects and settings.
|
120
|
+
|
121
|
+
=== Config Documentation DSL
|
122
|
+
|
123
|
+
AsciiDocsy introduces a domain-specific language (DSL) for _documenting_ theme configuration and other data files.
|
124
|
+
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.
|
125
|
+
|
126
|
+
This novel DSL lets you describe properties, and it will even read the existing value and list it as default.
|
127
|
+
You will see this `$doc:` syntax already used in `_docs/_data/theme/` files.
|
128
|
+
It is processed by the nestd includes: `config-api.asciidoc`, `config-api-objects.asciidoc`, and `config-api-properties.asciidoc`.
|
129
|
+
|
130
|
+
You may use this DSL to document your own data objects.
|
131
|
+
More documentation will appear here soon.
|
@@ -0,0 +1,70 @@
|
|
1
|
+
:page-permalink: /docs/theme/extend
|
2
|
+
= Extending the Theme
|
3
|
+
|
4
|
+
AsciiDocsy is designed to be customized without having to interfere with the core template, style, or script files.
|
5
|
+
|
6
|
+
The configuration system is elaborate, enabling control of most major features via YAML-formatted files.
|
7
|
+
Toggling features on and off and defining settings should mostly entail modifications to files of meticulously organized parameters.
|
8
|
+
|
9
|
+
The rest of the customization strategy involves supplementing or replacing AsciiDocsy's core files.
|
10
|
+
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.
|
11
|
+
|
12
|
+
== CSS
|
13
|
+
|
14
|
+
AsciiDocsy uses Sass and static CSS for style sourcing.
|
15
|
+
You are welcome to add files of either type.
|
16
|
+
|
17
|
+
Use the `_sass/_custom.scss` file to take advantage of Bootstrap variables, mixins, and utilities.
|
18
|
+
|
19
|
+
Use the `css/custom.css` file to override any precedent set in the cascade.
|
20
|
+
|
21
|
+
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.
|
22
|
+
|
23
|
+
== JavaScript
|
24
|
+
|
25
|
+
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.
|
26
|
+
|
27
|
+
Bootstrap provides numerous elements that enhance the way we shape and place novel elements.
|
28
|
+
However, jQuery (or another JS framework of your choice) is most helpful with post-render content enhancement and management.
|
29
|
+
|
30
|
+
When delivering HTML, JavaScript will almost always provide you with the final say.
|
31
|
+
|
32
|
+
As one example, AsciiDocsy uses JS-driven menus that dump into divs.
|
33
|
+
The terms-list generated on topic pages that contain glossary terms is also generated this way.
|
34
|
+
|
35
|
+
[[template-overrides]]
|
36
|
+
== Template Overrides
|
37
|
+
|
38
|
+
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.
|
39
|
+
Therefore, you may override any data file or template file by replacing it your local path.
|
40
|
+
|
41
|
+
The typical way to replace a file is to start with its upstream source.
|
42
|
+
Use [.cmd]`bundle info asciidocsy` to find the path to your local AsciiDocsy gem.
|
43
|
+
Otherwise, just go to the link:{theme_repo_www}[AsciiDocsy source repo] and copy/paste the file contents into your own.
|
44
|
+
|
45
|
+
[[template-hooks]]
|
46
|
+
== Template Hooks
|
47
|
+
|
48
|
+
Most of AsciiDocsy's core Liquid templates contain at least one [.term]*template hook*, letting you insert or replace code in strategic places.
|
49
|
+
|
50
|
+
Anywhere a file contains syntax like [.code]`{% include hook.liquid template="template_ext" spot="#some-place" %}`, a hook is available.
|
51
|
+
Defining this hook for your application will insert your own template into the parent template at that spot.
|
52
|
+
|
53
|
+
Hooked extensions are designated in [.path]`\_data/theme/extend.yml`.
|
54
|
+
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.
|
55
|
+
The last slot, [.tok.hooks-var]`<spot>`, references the `spot` argument of the hook.
|
56
|
+
|
57
|
+
.Example hook objects from [.path]`_data/theme/extend.yml`
|
58
|
+
[source,yaml]
|
59
|
+
----
|
60
|
+
include::{path_to_data_dir}/theme/extend.yml[tags=example]
|
61
|
+
----
|
62
|
+
|
63
|
+
<1> references an insertion point near the top of the calling file.
|
64
|
+
|
65
|
+
Supplemental files can be named however you wish.
|
66
|
+
|
67
|
+
[TIP]
|
68
|
+
The `breadcrumbs_html` data object is commented out by default.
|
69
|
+
To see this extension-hooks method in action, remove the comments and rebuild the site.
|
70
|
+
Page breadcrumbs will be replaced by a statement.
|
@@ -0,0 +1,62 @@
|
|
1
|
+
:page-permalink: /docs/theme/features/frontend
|
2
|
+
= AsciiDocsy Frontend Overview
|
3
|
+
|
4
|
+
The AsciiDocsy theme is not exactly groundbreaking in its layout.
|
5
|
+
This is by design.
|
6
|
+
|
7
|
+
There may be some cases when a unique format or layout is called for in documentation, but they are few and far between.
|
8
|
+
Users want predictability.
|
9
|
+
They want "`intuitive`" layouts where everything is where they expect.
|
10
|
+
|
11
|
+
In that spirit, AsciiDocsy's layout is conventional.
|
12
|
+
There are four navigation areas surrounding the content of each page.
|
13
|
+
|
14
|
+
image::asciidocsy-nav-model.png[title="AsciiDocsy's navigation model"]
|
15
|
+
|
16
|
+
Let's examine these navigation areas more closely.
|
17
|
+
|
18
|
+
== Site Menus and Navigation
|
19
|
+
|
20
|
+
Typically used for sitewide pages or key external links, the `#topnav` menu can accommodate a layer of nesting, if needed.
|
21
|
+
|
22
|
+
=== Subject Navigation (Left)
|
23
|
+
|
24
|
+
You are welcome to use the subject menu (`#subject-menu`) for anything you wish, of course, just as you are welcome to hide it.
|
25
|
+
It is set up as generically as possible, with repurposing in mind.
|
26
|
+
|
27
|
+
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.
|
28
|
+
|
29
|
+
[NOTE]
|
30
|
+
The subject menu does not at this time have a way of inferring a menu from the filesystem or even from page metadata (frontmatter).
|
31
|
+
While this functionality is possible, I have found it clunkier than centralized "`manifest`" data files that coordinate page and topic metadata.
|
32
|
+
|
33
|
+
=== Page Navigation (Right)
|
34
|
+
|
35
|
+
The right sidebar contains navigation and other features relevant to the current page or topic.
|
36
|
+
|
37
|
+
==== Page Links
|
38
|
+
|
39
|
+
Every page with a `page` or `topic` layout has a number of optional links to alter the page appearance or submit edits.
|
40
|
+
|
41
|
+
===== Data Edit Link
|
42
|
+
|
43
|
+
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.
|
44
|
+
|
45
|
+
image::thumb-topic-data-source-edit.png[title="AsciiDocsy lets you link to the AsciiDoc source and the underlying YAML file."]
|
46
|
+
|
47
|
+
See this feature in action in the <</docs/theme/config/api-reference#,Configuration API Reference>>.
|
48
|
+
|
49
|
+
==== Topic TOC
|
50
|
+
|
51
|
+
The topic table-of-contents is generated by Bootstrap's scrollspy component.
|
52
|
+
The client (browser) renders headers of designated levels into TOC items with anchor links.
|
53
|
+
|
54
|
+
[NOTE]
|
55
|
+
This feature does not use AsciiDoc's built-in TOC generator, which can still be embedded in the page itself.
|
56
|
+
|
57
|
+
The TOC remains in a static position as you scroll the page, tracking your position by highlighting the appropriate item in the TOC.
|
58
|
+
|
59
|
+
=== Company Navigation (Bottom)
|
60
|
+
|
61
|
+
The company nav consists of up to five columns of links.
|
62
|
+
Link hrefs can draw data from additional sources, as well.
|
@@ -0,0 +1,71 @@
|
|
1
|
+
:page-permalink: /docs/theme/setup/bootstrap
|
2
|
+
:page-togglers: user-os
|
3
|
+
= "`Bootstrap`" this Theme
|
4
|
+
|
5
|
+
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.
|
6
|
+
|
7
|
+
Cool.
|
8
|
+
The first step is to review the entries in `_config.yml` and translate them to your own application.
|
9
|
+
|
10
|
+
[IMPORTANT]
|
11
|
+
The site at `localhost:4000` will regenerate incrementally whenever you change pretty much any file in the repo.
|
12
|
+
A key exception is `_config.yml`.
|
13
|
+
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`.
|
14
|
+
|
15
|
+
AsciiDocsy is designed to be modified mostly through YAML configuration and datafile settings.
|
16
|
+
See link:{theme_docs_www}/theme/config[Configuring AsciiDocsy] in the theme docs for more.
|
17
|
+
|
18
|
+
== LiquiDoc Ops Integration (More Coming Soon)
|
19
|
+
|
20
|
+
This theme is meant to go be embedded in the [.path]`theme/` path of a LiquiDoc Ops application (probably as [.path]`theme/asciidocsy/`).
|
21
|
+
Repoint any Jekyll configuration settings from `theme/[<theme-name>/]` to this new path.
|
22
|
+
|
23
|
+
== Deploying an AsciiDocsy Jekyll Site
|
24
|
+
|
25
|
+
The build operation generates static HTML files and other artifacts that can be deployed to any static-site server.
|
26
|
+
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.
|
27
|
+
|
28
|
+
=== Automation with Netlify
|
29
|
+
|
30
|
+
My preferred out-of-box deployment with full production hosting as well as staging capabilities is definitely Netlify.
|
31
|
+
You can sign in with your GitHub/GitLab authorization and have site up in under a minute.
|
32
|
+
|
33
|
+
. Create a Netlify account.
|
34
|
+
. Add a site.
|
35
|
+
. Select your repo.
|
36
|
+
. The build command ([.cmd]`bundle exec jekyll build`) and target path ([.path]`_site/`) should already be filled out.
|
37
|
+
|
38
|
+
You can trigger builds through the Netlify UI or by simply merging a commit to the `main` (or other default) branch.
|
39
|
+
|
40
|
+
[NOTE]
|
41
|
+
If you set up CI/CD on another such platform, please contribute the instructions here.
|
42
|
+
I have no affiliation with or allegiance to Netlify or GitHub.
|
43
|
+
|
44
|
+
=== DIY DocOps
|
45
|
+
|
46
|
+
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.
|
47
|
+
|
48
|
+
==== Build Operation
|
49
|
+
|
50
|
+
You defintely want to:
|
51
|
+
|
52
|
+
. Require Ruby 2.4+.
|
53
|
+
. Run [.cmd]`bundle install`.
|
54
|
+
. Run [.cmd]`bundle exec jekyll build`.
|
55
|
+
. Copy files from the destination dir (`_site/` by default) to your staging or production server.
|
56
|
+
|
57
|
+
==== Continuous Integration
|
58
|
+
|
59
|
+
You will probably also want to:
|
60
|
+
|
61
|
+
* Establish build triggers for:
|
62
|
+
** merge/pull requests (staging deploy)
|
63
|
+
** merges to the main branch (production deploy)
|
64
|
+
* Establish tests, perhaps starting with:
|
65
|
+
** link:https://github.com/gjtorikian/html-proofer[HTMLProofer] for link and HTML checking
|
66
|
+
** link:https://github.com/errata-ai/vale[Vale] for conetnt/style linting
|
67
|
+
|
68
|
+
==== Deployment
|
69
|
+
|
70
|
+
The site is configured to be served at a domain or subdomain root, such as `www.yourdocumentationwebsite.com` or `docs.yourcompan.io`.
|
71
|
+
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.
|
@@ -0,0 +1,65 @@
|
|
1
|
+
:page-permalink: /docs/theme/setup/environment
|
2
|
+
:page-togglers: user-os
|
3
|
+
= Setting Up a Writing/Development Environment
|
4
|
+
|
5
|
+
A proper Jekyll/AsciiDocsy environment has a few prerequisites.
|
6
|
+
|
7
|
+
The entire toolchain is Ruby-based, so once you have the right version of <<ruby>>, it is pretty easy to get up and running.
|
8
|
+
|
9
|
+
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>>.
|
10
|
+
|
11
|
+
[[ruby]]
|
12
|
+
== Ruby
|
13
|
+
|
14
|
+
include::{path_to_readme}[tags=requirements-ruby]
|
15
|
+
|
16
|
+
[[terminal]]
|
17
|
+
== Terminal & Shell
|
18
|
+
|
19
|
+
[.os-win]
|
20
|
+
--
|
21
|
+
*Windows* users still need a terminal to pass commands to the WSL shell.
|
22
|
+
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.
|
23
|
+
--
|
24
|
+
|
25
|
+
[.os-mac]
|
26
|
+
For *MacOS* users who do not already have a preferred terminal, link:https://iterm2.com[iTerm2] is a common favorite.
|
27
|
+
|
28
|
+
[.os-nix]
|
29
|
+
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].
|
30
|
+
|
31
|
+
=== Zsh
|
32
|
+
|
33
|
+
On *all platforms*, I strongly recommend anyone new to the commandline/shell operations immediately [.tip]*install Zsh as default shell*.
|
34
|
+
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.
|
35
|
+
|
36
|
+
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.
|
37
|
+
|
38
|
+
There are lots of resources to enhance the experience, including the awesome link:https://ohmyz.sh[addons package OhMyZsh]!
|
39
|
+
Use their link:https://github.com/ohmyzsh/ohmyzsh/wiki/Installing-ZSH[Zsh install guide] to make sure you've got the best setup.
|
40
|
+
|
41
|
+
[[code-editor]]
|
42
|
+
== Code Editor
|
43
|
+
|
44
|
+
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).
|
45
|
+
The distinctions are not very important, as long as they integrate with AsciiDoc and YAML.
|
46
|
+
|
47
|
+
If you already have a preference, that's the editor for you.
|
48
|
+
If you are unsure, here is a brief guide to the top contenders.
|
49
|
+
|
50
|
+
VS Code::
|
51
|
+
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.
|
52
|
+
Extend native YAML support with https://github.com/redhat-developer/vscode-yaml[RedHat's extension].
|
53
|
+
|
54
|
+
Atom::
|
55
|
+
Maintained by GitHub, https://atom.io/[Atom] was for years the main choice for AsciiDoc writers.
|
56
|
+
You will want to add at least the asciidoc-language and asciidoc-preview packages.
|
57
|
+
|
58
|
+
InelliJ IDEA::
|
59
|
+
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.
|
60
|
+
Extend https://plugins.jetbrains.com/plugin/7792-yaml-ansible-support[YAML support].
|
61
|
+
|
62
|
+
AsciiDocFX::
|
63
|
+
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.
|
64
|
+
|
65
|
+
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.
|
@@ -0,0 +1,10 @@
|
|
1
|
+
:page-permalink: /docs/theme/setup/quickstart
|
2
|
+
:page-togglers: user-os
|
3
|
+
include::README.adoc[tags=globals]
|
4
|
+
:page-canonical: {theme_repo_www}/
|
5
|
+
= Quickstart Demo
|
6
|
+
|
7
|
+
To see AsciiDocsy and Jekyll in action, try building the demo site.
|
8
|
+
|
9
|
+
// includes the DOCS repo's own README file
|
10
|
+
include::README.adoc[tags=quickstart-build]
|
@@ -0,0 +1,31 @@
|
|
1
|
+
:page-permalink: /docs/theme/setup
|
2
|
+
:page-togglers: user-os
|
3
|
+
= AsciiDocsy Setup
|
4
|
+
|
5
|
+
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.
|
6
|
+
|
7
|
+
[.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>>.
|
8
|
+
|
9
|
+
[.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.
|
10
|
+
|
11
|
+
== Basic Installation
|
12
|
+
|
13
|
+
Use either of link:https://jekyllrb.com/docs/themes/#installing-a-theme[Jekyll's supported methods] for adding a gem-based theme to a Jekyll application.
|
14
|
+
|
15
|
+
We highly recommend using Bundler and a Gemfile.
|
16
|
+
|
17
|
+
. Enter AsciiDocsy as a plugin to Jekyll.
|
18
|
+
+
|
19
|
+
[source,ruby]
|
20
|
+
.Gemfile entry
|
21
|
+
----
|
22
|
+
include::Gemfile[tags=jekyll-plugins]
|
23
|
+
----
|
24
|
+
|
25
|
+
. Set AsciiDocsy as your theme.
|
26
|
+
+
|
27
|
+
[source,yaml]
|
28
|
+
._config.yml
|
29
|
+
----
|
30
|
+
theme: asciidocsy
|
31
|
+
----
|
@@ -0,0 +1,172 @@
|
|
1
|
+
:page-permalink: /docs/theme/syntax
|
2
|
+
= Syntax Highlighting
|
3
|
+
|
4
|
+
AsciiDocsy comes with syntax highlighting by Highlight.js, but Jekyll and Asciidoctor both support other highlighters, including Rouge and Pygments.
|
5
|
+
|
6
|
+
[NOTE]
|
7
|
+
AsciiDocsy will eventually incorporate all upstream-supported highlighter options.
|
8
|
+
|
9
|
+
== Examples
|
10
|
+
|
11
|
+
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.
|
12
|
+
|
13
|
+
=== Structured Query Language (SQL)
|
14
|
+
|
15
|
+
[source,sql]
|
16
|
+
----
|
17
|
+
CREATE TABLE "topic" (
|
18
|
+
"id" serial NOT NULL PRIMARY KEY,
|
19
|
+
"forum_id" integer NOT NULL,
|
20
|
+
"subject" varchar(255) NOT NULL
|
21
|
+
);
|
22
|
+
ALTER TABLE "topic"
|
23
|
+
ADD CONSTRAINT forum_id FOREIGN KEY ("forum_id")
|
24
|
+
REFERENCES "forum" ("id");
|
25
|
+
|
26
|
+
-- Initials
|
27
|
+
insert into "topic" ("forum_id", "subject")
|
28
|
+
values (2, 'D''artagnian');
|
29
|
+
----
|
30
|
+
|
31
|
+
=== HTML
|
32
|
+
|
33
|
+
[source,html]
|
34
|
+
----
|
35
|
+
<!DOCTYPE html>
|
36
|
+
<title>Title</title>
|
37
|
+
|
38
|
+
<style>body {width: 500px;}</style>
|
39
|
+
|
40
|
+
<script type="application/javascript">
|
41
|
+
function $init() {return true;}
|
42
|
+
</script>
|
43
|
+
|
44
|
+
<body>
|
45
|
+
<p checked class="title" id='title'>Title</p>
|
46
|
+
<!-- here goes the rest of the page -->
|
47
|
+
</body>
|
48
|
+
----
|
49
|
+
|
50
|
+
=== AsciiDoc
|
51
|
+
|
52
|
+
[source,asciidoc]
|
53
|
+
----
|
54
|
+
Here is some text with a link:/[link to the homepage].
|
55
|
+
|
56
|
+
Followed by some *bold* and:
|
57
|
+
|
58
|
+
* An
|
59
|
+
* Unordered
|
60
|
+
* List
|
61
|
+
|
62
|
+
definition:: list
|
63
|
+
----
|
64
|
+
|
65
|
+
=== Ruby
|
66
|
+
|
67
|
+
[source,ruby]
|
68
|
+
----
|
69
|
+
# The Greeter class
|
70
|
+
class Greeter
|
71
|
+
def initialize(name)
|
72
|
+
@name = name.capitalize
|
73
|
+
end
|
74
|
+
|
75
|
+
def salute
|
76
|
+
puts "Hello #{@name}!"
|
77
|
+
end
|
78
|
+
end
|
79
|
+
|
80
|
+
g = Greeter.new("world")
|
81
|
+
g.salute
|
82
|
+
----
|
83
|
+
|
84
|
+
=== JavaScript
|
85
|
+
|
86
|
+
[source,javascript]
|
87
|
+
----
|
88
|
+
function $initHighlight(block, cls) {
|
89
|
+
try {
|
90
|
+
if (cls.search(/\bno\-highlight\b/) != -1)
|
91
|
+
return process(block, true, 0x0F) +
|
92
|
+
` class="${cls}"`;
|
93
|
+
} catch (e) {
|
94
|
+
/* handle exception */
|
95
|
+
}
|
96
|
+
for (var i = 0 / 2; i < classes.length; i++) {
|
97
|
+
if (checkCondition(classes[i]) === undefined)
|
98
|
+
console.log('undefined');
|
99
|
+
}
|
100
|
+
|
101
|
+
return (
|
102
|
+
<div>
|
103
|
+
<web-component>{block}</web-component>
|
104
|
+
</div>
|
105
|
+
)
|
106
|
+
}
|
107
|
+
|
108
|
+
export $initHighlight;
|
109
|
+
----
|
110
|
+
|
111
|
+
=== JSON
|
112
|
+
|
113
|
+
[source,json]
|
114
|
+
----
|
115
|
+
[
|
116
|
+
{
|
117
|
+
"title": "apples",
|
118
|
+
"count": [12000, 20000],
|
119
|
+
"description": {"text": "...", "sensitive": false}
|
120
|
+
},
|
121
|
+
{
|
122
|
+
"title": "oranges",
|
123
|
+
"count": [17500, null],
|
124
|
+
"description": {"text": "...", "sensitive": false}
|
125
|
+
}
|
126
|
+
]
|
127
|
+
----
|
128
|
+
|
129
|
+
=== YAML
|
130
|
+
|
131
|
+
[source,yaml]
|
132
|
+
----
|
133
|
+
---
|
134
|
+
# comment
|
135
|
+
string_1: "Bar"
|
136
|
+
string_2: 'bar'
|
137
|
+
string_3: bar
|
138
|
+
inline_keys_ignored: sompath/name/file.jpg
|
139
|
+
keywords_in_yaml:
|
140
|
+
- true
|
141
|
+
- false
|
142
|
+
- TRUE
|
143
|
+
- FALSE
|
144
|
+
- 21
|
145
|
+
- 21.0
|
146
|
+
- !!str 123
|
147
|
+
"quoted_key": &foobar
|
148
|
+
bar: foo
|
149
|
+
foo:
|
150
|
+
"foo": bar
|
151
|
+
|
152
|
+
reference: *foobar
|
153
|
+
|
154
|
+
multiline_1: |
|
155
|
+
Multiline
|
156
|
+
String
|
157
|
+
multiline_2: >
|
158
|
+
Multiline
|
159
|
+
String
|
160
|
+
multiline_3: "
|
161
|
+
Multiline string
|
162
|
+
"
|
163
|
+
|
164
|
+
ansible_variables: "foo {{variable}}"
|
165
|
+
|
166
|
+
array_nested:
|
167
|
+
- a
|
168
|
+
- b: 1
|
169
|
+
c: 2
|
170
|
+
- b
|
171
|
+
- comment
|
172
|
+
----
|