Theme Configuration API

This reference is highly experimental. I’ve only spent about 2 hours coding this as an example of a novel domain-specific language (DSL) reference parsed from YAML by Liquid into AsciiDoc for rendering as HTML (or PDF, etc).

Consider this to be rudimentary documentation generated from data structures found in config.yml. This would be better generated from a _schema-like version of these data objects, referencing them with metadata about each block of properties in each feature object. Instead, we are using the objects directly, supplemented by an optional $docs objects embedded in the config data structure.

Also, due to object nesting, lots more recursive processing needs to happen. The truth is, a simple configuration file that can be commented inline and must be edited in place is not great fodder for an API reference, but I wanted to demonstrate it.

But do look at the AsciiDoc and YAML sources (see links to the right ) for this page if you need inspiration for your own complex content.

POLICIES

site.data.theme.policies

Defines policies regarding privacy, content display, access, etc.

GDPR Policies

site.data.theme.policies.gdpr

Groups cookies by use to let users select which cookies to permit.

Properties

site.data.theme.policies.gdpr.types
usage

The categories of cookies users can toggle on/off.
slug

Slug for the category.
text

User-facing descriptor for the category.
cookies

Array of cookie names in the category.
default

{"slug"⇒"essential", "text"⇒"Just the cookie to remember these preferences.", "cookies"⇒["cookieControlPrefs"]}{"slug"⇒"preferences", "text"⇒"Cookies to recall style and version choices made in the app.", "cookies"⇒["syntax-style", "skin-style", "switcher_user-os"]}{"slug"⇒"analytics", "text"⇒"Uses cookies to anonymously report how you use the site so we can improve the experience.", "cookies"⇒["google-analytics"]}{"slug"⇒"commercial", "text"⇒"We don’t use this kind of cookie anywhere on our site.", "cookies"⇒[]}

Authorizations

site.data.theme.policies.authorizations

Defaults

site.data.theme.policies.defaults

STRINGS

site.data.theme.strings

Theme strings organized by container block/element. Documentation in source file only.

site.data.theme.strings.footer

Strings for the footer of the document.

See-also

site.data.theme.strings.see-also

Strings for the see-also segment

BLOCKS

site.data.theme.blocks

Placement and design of various layout elements.

Page-header

site.data.theme.blocks.page-header

Settings for the header area of the layout

Properties

site.data.theme.blocks.page-header.show.logo.source
usage

Path of header logo image file; allows Liquid
type

String
default

{{ images_url }}/logo.png
site.data.theme.blocks.page-header.show.logo.width
usage

Width of the header logo image
type

String
default

50px

Page-footer

site.data.theme.blocks.page-footer

Settings for the footer area of the layout

Properties

site.data.theme.blocks.page-footer.show.logo.source
usage

Path of footer logo image file; allows Liquid
type

String
default

{{ images_url }}/docops-labs-logo.png
site.data.theme.blocks.page-footer.show.logo.width
usage

Width of the footer logo image
type

String
default

150px
site.data.theme.blocks.page-footer.opts.first-col-class
usage

The class of the first column in the footer
type

String

site.data.theme.blocks.social-links

Settings for social links.

Properties

default

footer

FORMS

site.data.theme.forms

Ad-hoc forms for the theme.

Feedback-form

site.data.theme.forms.feedback-form

Populates the feedback form and results.

Properties

site.data.theme.forms.feedback-form.show.name
default

Feedback, please.
site.data.theme.forms.feedback-form.show.text
default

Did you find this page helpful?
site.data.theme.forms.feedback-form.show.icon
default

fa fa-clipboard
site.data.theme.forms.feedback-form.send.opts
usage

Array items are objects that contain:

slug

Required, value string.
text

Optional, text label to show.
echo

Response to show after this option is selected.
icon

Optional, icon to display for this option.
type

Array
default

{"slug"⇒"yes", "text"⇒"Yes", "echo"⇒"That’s great! Do let us know if you have more to say.\n", "icon"⇒"fa fa-trophy"}{"slug"⇒"no", "text"⇒"No", "echo"⇒"We are sorry to hear that.\n\nMore text\n", "icon"⇒"frown-o"}{"slug"⇒"some", "text"⇒"Partly", "echo"⇒"Okay, thanks for your honesty.\n\nMore text\n", "icon"⇒"fa fa-line-chart"}

GDPR Alert

site.data.theme.forms.gdpr-alert

NOT YET IMPLEMENTED.

STYLES

site.data.theme.styles

Custom styles for elements of the theme

site.data.theme.styles.nav-site

site.data.theme.styles.logo

Color

site.data.theme.styles.color

RELEASE HX

site.data.theme.release-hx

Template for parsing version history into Release Notes and/or Changelog

Policy

site.data.theme.release-hx.policy

Rn

site.data.theme.release-hx.rn

Cl

site.data.theme.release-hx.cl

Parts

site.data.theme.release-hx.parts

Types

site.data.theme.release-hx.types

Tags

site.data.theme.release-hx.tags

Roles

site.data.theme.release-hx.roles

Cats

site.data.theme.release-hx.cats

Defaults

site.data.theme.release-hx.defaults

Patterns

site.data.theme.release-hx.patterns

SCRIPTS

site.data.theme.scripts

Defines references to JavaScript resources.

site.data.theme.scripts.head

Tail

site.data.theme.scripts.tail

SEMANTICS

site.data.theme.semantics

Defines inline and block-level semantic elements

Inline

site.data.theme.semantics.inline

Blocks

site.data.theme.semantics.blocks

PAGE ACTIONS: TOPIC

site.data.theme.page-actions.topic

Peel

site.data.theme.page-actions.topic.peel

Make the page print-friendly by removing the sidebars.

Properties

site.data.theme.page-actions.topic.peel.text
default

Print-friendly
site.data.theme.page-actions.topic.peel.icon
default

fa fa-newspaper-o
site.data.theme.page-actions.topic.peel.func
default

``

Edit

site.data.theme.page-actions.topic.edit

Link to edit this topic in Git.

Properties

site.data.theme.page-actions.topic.edit.text
default

Edit this topic
site.data.theme.page-actions.topic.edit.icon
default

fa fa-pencil-square

Data

site.data.theme.page-actions.topic.data

Link to edit this topic datasource in Git.

Properties

site.data.theme.page-actions.topic.data.text
default

Edit topic datasource
site.data.theme.page-actions.topic.data.icon
default

fa fa-database

Make

site.data.theme.page-actions.topic.make

Link to make a new topic in Git.

Properties

site.data.theme.page-actions.topic.make.text
default

Create a (sub)topic
site.data.theme.page-actions.topic.make.icon
default

fa fa-file-text-o

Open Docs Ticket

site.data.theme.page-actions.topic.open-docs

Link to making a docs ticket.

Properties

site.data.theme.page-actions.topic.open-docs.text
default

Open a docs ticket.
site.data.theme.page-actions.topic.open-docs.icon
default

fa fa-ticket
site.data.theme.page-actions.topic.open-docs.path
default

/new?labels=documentation

Open Subject Ticket

site.data.theme.page-actions.topic.open-subj

Link to making a subject (product) ticket.

Properties

site.data.theme.page-actions.topic.open-subj.text
default

Open a product ticket.
site.data.theme.page-actions.topic.open-subj.icon
default

fa fa-tag
site.data.theme.page-actions.topic.open-subj.path
default

/new

PAGE ACTIONS: PAGE

site.data.theme.page-actions.page

Edit

site.data.theme.page-actions.page.edit

Link to edit this page.

Properties

site.data.theme.page-actions.page.edit.text
default

Edit this page in Git.
site.data.theme.page-actions.page.edit.icon
default

fa fa-pencil

Data

site.data.theme.page-actions.page.data

Link to edit this page’s datasource.

Properties

site.data.theme.page-actions.page.data.text
default

Edit page datasource in Git.
site.data.theme.page-actions.page.data.icon
default

fa fa-database

Make

site.data.theme.page-actions.page.make

Create a new page in Git.

Properties

site.data.theme.page-actions.page.make.text
default

Suggest a new page
site.data.theme.page-actions.page.make.icon
default

fa fa-file-text-o

site.data.theme.navigation

All navigation elements are defined here.

site.data.theme.navigation.anchor-links

Adds self-referential links to all headers of the listed types.

Properties

usage

Comma-delimited list of heading elements to bookmark
type

String
default

h2,h3,h4,h5

Subject Menu

site.data.theme.navigation.subject-menu

Determines the source and display of the subject navigation menu.

Properties

site.data.theme.navigation.subject-menu.opts.show.type.icons
type

String

Table of Contents

site.data.theme.navigation.toc

Shows and sets the depth of the table of contents for a topic/page.

Properties

site.data.theme.navigation.toc.show.text
default

In this topic…
site.data.theme.navigation.toc.show.spot
default

#sidebar-right
site.data.theme.navigation.toc.show.opts.header-level-depth
default

h3

Page Breadcrumbs

site.data.theme.navigation.breadcrumbs

Displays and designs the breadcrumb trail.

Properties

site.data.theme.navigation.breadcrumbs.show.home
usage

The label for the base crumb
type

String
default

Home
site.data.theme.navigation.breadcrumbs.show.opts.delim
usage

Character(s) to insert between crumbs
type

String
default

>

site.data.theme.search

Defines the fields/results for search forms

Search the site

site.data.theme.search.site

Enables users to search all pages in the site, including non-topics

Properties

site.data.theme.search.site.show.text
default

Search non-docs PAGES…
site.data.theme.search.site.show.icon
site.data.theme.search.site.show.spot
default

#nav-site
site.data.theme.search.site.show.meta.index

Search current subject

site.data.theme.search.subject

Enables users to search all topics in a subject

Properties

site.data.theme.search.subject.show.text
default

Search subject TOPICS…
site.data.theme.search.subject.show.icon
default

fa fa-search
site.data.theme.search.subject.show.spot
default

#sidebar-left

EXTEND

site.data.theme.extend

Listing of extension hooks, as described in Extend the Theme

Hooks

site.data.theme.extend.hooks

Feedback, please.