LiquiDoc Admin and User Manual

Valid data sources come in a few different types. There are the built-in data types (YAML, JSON, XML, CSV) vs free-form type (files processed using regular expressions, designated by the regex data type). There is also a divide between simple one-record-per-line data types (CSV and regex), which produce one set of parameters for every line in the source file, versus nested data types that can reflect far more complex structures.

LiquiDoc can directly convert any supported semi-structured data input format to either YAML or JSON output. Simply provide no template parameter, and make sure the output file has a proper extension (.yml or .json).

In addition to (or instead of) data files, parse operations accept fixed variables and environment variables.

Parse actions can ingest an indefinite number of data sources, with some restrictions.

The parse action’s data: parameter can accept an array of paths to any supported semi-structured data format, given the following standard file extensions (.csv, .yml, .json, .xml). Any other file, whether nonstandard format or nonstandard file extension, must first be converted to a standard format.

In this example, we imagine generating a couple of files useful to different parts of a documentation app, including common strings and language settings. In each Liquid template, we have access to several data objects.

The vars. scope carries anything passed as variables: in the build step. For example, {{vars.language.full}} would resolve to English in this example build.

For the ingested files, a scope is named after the source filename, minus its extension. In the above example, we could access variables from common-en.json as {{common-en.keyname}}, and so forth.

LiquiDoc’s multi-file datasource ingest works very similarly to Jekyll’s templating, where always-available data objects are derived from files in the data directory. The key difference is that files must be explicitly listed for each parse action in order for their data to be available.

This functionality also resembles the multi-file attributes ingest in render operations, using the same parameter, data:. But whereas attribute-file ingest accepts a sub-data block indicator, this feature is redundant and thus not available in parse operations. Entire files are ingested and passed to the designated templates during parsing.

After this parsing, files are written in any of the given output formats, or else just written to console as STDOUT (when you add the --stdout flag to your command or set output: stdout in your config file). Liquid templates can be used to produce any plaintext format imaginable. Just format valid syntax with your source data and Liquid template, then save with the proper extension, and you’re all set.

Static-site generators are critical tools to just about any docs-as-code infrastructure. Starting with Jekyll but soon to add more (Awestruct and possibly Grain next), each generator added will maintain all of its capabilities and do most of the heavy lifting.

LiquiDoc’s role is primarily to help your preferred SSG handle your source in ways consistent with any other rendering and file managing your docs codebase requires. For example, the jekyll-asciidoc extension that enables Jekyll builds to parse AsciiDoc markup only honors attributes set in Jekyll config files. Therefore, just before triggering the build, LiquiDoc loads all the accummulated AsciiDoc parameters into a new config file from which Jekyll draws AsciiDoc attribute assignments.

The backend: designation of jekyll is required, and at least one file under properties:files: is strongly encouraged for proper Jekyll behavior. LiquiDoc will write an additional YAML file containing all of the Asciidoctor attributes, to be appended to this list when the build command is run. This captures attributes offered up in the action-level data: file and in the attributes: section of the build step.

The arguments: block is made up of key-value parameters that establish or override any Jekyll config settings.

For basic render actions, the source: file and other .adoc files determine most of the rest of the content source files (if any) using AsciiDoc includes. But Asciidoctor renderings can be configured and manipulated by attribute settings at other stages. Basically, we are trying to maximize our readiness to ingest document data and build properties from a wide range of sources. This way inline substitutions can be made out of data living outside the source tree of any particular document, passed into the document build in the form of YAML data converted into — you guessed it — AsciiDoc attributes.

LiquiDoc provides several means for adding attributes to your documents, in addition to the ways you might be used to setting attributes (inside your docfiles and command line). They are listed below in the order of assignment/substitution. Therefore, an identical value defined explicitly in each subsequent space will overwrite any set in the previous stages.

The order of substitution is as follows.

After that, we’ll demonstrate even more ways to ingest datasets.

Certain AsciiDoc/Asciidoctor settings are determinant enough that they can be set using parameters in the build config. Establishing these as per-build settings in your config file will override anywhere else they are set, except on the command line.

If you’re using Jekyll to build sites, LiquiDoc makes indexing your files with the Algolia cloud search service a matter of configuration, not development. The heavy lifting is performed by the jekyll-algolia plugin, but LiquiDoc can handle indexing even a complex site by using the same configuration that built your HTML content (which is what Algolia actually indexes).

Two hard-coding steps are required to prep your source to handle Algolia index pushes.

Indexing is invoked by command-line flags. Add --search-index-push or --search-index-dry along with the --search-api-key='your-admin-api-key-here' argument in order to invoke the indexing operation. The --search-index-dry flag merely tests content packaging, whereas --search-index-push connects to the Algolia REST API and attempt to push your content for indexing and storage.

This operation performs a complete build, including each render operation, before the Algolia plugin processes content and pushes each build to the indexing service, in turn.

For testing purposes, however, spinning up a local webserver with the same stroke that you build a site is pretty rewarding and time saving, so we’ll start there.

For now, this functionality is limited to adding a --deploy flag to your liquidoc command. This will attempt to serve files from the destination: set for the associated Jekyll build.

To capture the output of a given command, add options: to the execute instructions. Writing results to a file is enabled with the outfile: option.

When writing results to an outfile, optionally insert text at the top or bottom of your new file using prepend: and append: settings.

The status of each command is tracked, and errors that result in an exit status of 1 can optionally halt the entire LiquiDoc routine. To cause this, you must add an error: block to the options, with a child parameter: response: exit, as shown above. The default behavior is to continue processing (response: ignore).

You may optionally provide a second child, message: followed by the string users will see when they encounter an error here. If the command throws an error, this message will appear, even if you choose not to exit processing.

Ingested data objects can take the form of serialized arrays or non-serialized structures.

For data sourced in CSV format or extracted through regex source parsing, all data is passed to the Liquid template parser as an array object called data, containing one or more “rows” of data. This extends to YAML and JSON data formed as serialized at their root.

Once ingested, such data can be expressed using the data. scope.

XML files typically contains arrays/collections nested in parent elements.

For nested arrays of this type, the key name is that of the containing element.

Data sourced as non-serialized structures in YAML, XML, or JSON may be similarly expressed, using their nested identifiers, with keys determined in the origin contents.

Additional variables passed during gem execution may be expressed under the vars. scope ({{vars.variable_key}}) or at the root ({{variable_key}}, for direct conversions).

Looping through known data formats is fairly straightforward. A for loop iterates through your data, item by item. Each item or row contains one or more key-value pairs.

In Example — rows.asciidoc Liquid template for outputting AsciiDoc plaintext markup, we’re instructing Liquid to iterate through our data items, generating a data structure called row each time. The double-curly-bracketed tags convey variables to evaluate. This means {{ row.name }} is intended to express the value of the name parameter in the item presently being parsed. The other curious marks such as :: and [horizontal.simple] are AsciiDoc markup — they are the formatting we are trying to introduce to give the content form and semantic relevance.

The above (Example — rows.asciidoc Liquid template for outputting AsciiDoc plaintext markup) would generate the following:

The generically styled AsciiDoc rich text reflects the distinctive structure with (very little) more elegance.

The implied structures are far more evident when displayed as HTML derived from Asciidoctor parsing of the LiquiDoc-generated AsciiDoc source (from Example — AsciiDoc-formatted output).

Remember, all this started out as that little old free-form text file.

LiquiDoc’s core Liquid templating engine uses standard Liquid tags and filters, with some key exceptions, expressed below. For the full LiquiDoc Liquid API, see the complete reference.

The best way to use LiquiDoc is with a configuration file. This not only makes the command line much easier to manage (requiring just a configuration file path argument), it also adds the ability to perform more complex build routines and manage them with source control.

Here is very simple build routine instructed by a LiquiDoc config:

When you have established a configuration file, you can call it with the option -c on the command line.

As long as we are invoking Liquid to manipulate files with templates in our parse operations, we had might as well use it to parse our config files themselves. This is an advanced procedure for injecting programmatic functionality into your builds. If you are comfortable with Liquid templating and basic LiquiDoc build config structure, you are ready to learn dynamic configuration.

As of LiquiDoc 0.9.0, config files can be parsed (preprocessed) at the top of a build. That is, your config files can contain variables, conditionals, and iterative loops — any Liquid tags and filters supported by LiquiDoc.

All you have to do is (1) add Liquid tags to your YAML configuration file. If the Liquid markup in your config file expects variables, pass those variables on the liquidoc CLI using --var key=value.

Here is a table of established configuration settings, as they pertain to each key LiquiDoc action.

*The output setting is considered optional for render operations because static site generations target a directory set in the SSG’s config file.

LiquiDoc supports all standard Liquid tags and filters, as well as all of Jekyll’s custom Liquid filters.