LiquiDoc is a documentation build utility for true single-sourcing of technical content and data. It is especially suited for documentation projects with various required output formats from complex, single-sourced codebases, but it is intended for any project with complex, versioned input data for use in docs, user interfaces, and even back-end code. The highly configurable command-line utility (and Ruby gem) engages template engines to parse complex data into rich text output, from blogs to books to knowledge bases to slide presentations.
Content source is formatted in the incredible AsciiDoc lightweight markup language. Data sources can be flat files in formats such as XML (eXtensible Markup Language), JSON (JavaScript Object Notation), CSV (comma-separated values), and our preferred human-editable format: YAML (acronym in dispute). LiquiDoc also accepts regular expressions to parse unconventionally formatted files.
LiquiDoc relies heavily on the Asciidoctor rendering engine, which produces HTML and PDF documents as well as complete static websites, the latter via Jekyll. Output can be pretty much any flat file, with automatic data conversions to JSON and YAML, as well as rich-text/multimedia formats like HTML, PDF, slide decks, and more.
|
📎
|
While the first two releases of LiquiDoc were published under the MIT license by my former employer, I do not believe the originating repo will be maintained. Therefore, as of version 0.3.0, I maintain this fork under the MIT license. More in Contributing and Licensing. |
LiquiDoc is a build tool for software-documentation projects or for the documentation component of a larger software project. Unlike tools that are mere converters, LiquiDoc can be configured to perform multiple consecutive routines for generating content from multiple data/content sources, each output in various formats based on distinct templates and themes. It can be integrated into build- and package-management systems and deployed for continuous integration (CI).
LiquiDoc pulls together the underlying “AJYL” technologies: AsciiDoc technical markup (via Asciidoctor), YAML data structures, and the Liquid templating format/engine, built using the Jekyll static-site generator and JAMstack components and services for publishing and delivery. It is developed in coordination with the LiquiDoc Content Management Framework, a recommended architecture, strategies, and conventions for building robust documents with LiquiDoc. LiquiDoc itself is fairly open-ended, supporting various configurations of dependent platforms Jekyll and Asciidoctor.
The utility currently provides for basic configuration of build jobs, and it can be incorporated into build toolchains. The gem does not have a formalized Ruby API yet, but the command-line interface is very powerful, especially combined with build configs formatted in YAML enhanced by Liquid markup for dynamic parsing of routines at buildtime. (See [dynamic-config].) From any given data file, multiple template-driven parsing operations can be performed to produce totally different output formats from the same content and data sources.
Upcoming capabilities include a secondary publish function for generating Asciidoctor output from data-driven AsciiDoc-formatted files to ePub and even HTML/JavaScript slide presentations.
See this project’s GitHub issues for upcoming features, and feel free to add your own requests.
|
📎
|
Your system must be running Ruby 2.3 or later (2.6+ recommended). See rubyinstaller.org if you’re on Windows. MacOS and Linux users should use a native packaging manager (Homebrew for MacOS, apt-get/dpkg/rpm/etc for Linux distros) or a Ruby package manager like rbenv or or RVM. |
-
Create a file called
Gemfilein your project’s root directory. -
Populate the file with LiquiDoc dependencies.
A LiquiDoc project Gemfilesource 'https://rubygems.org' gem 'liquidoc'
💡A version of this file is included in the LiquiDoc CMF bootstrap repo, which is a recommended way to quickstart or demo a LiquiDoc CMF application. -
Open a terminal (command prompt).
If you don’t have a preferred terminal application, use your OS’s magic search and look for
terminal. -
Navigate to your project root directory.
Examplecd Documents/workspace/my_project
-
Run
bundle installto prepare dependencies.If you do not have Bundler installed, Ruby will tell you. Enter
gem install bundler, let Bundler install, then repeat this step.
Cool! LiquiDoc should now be ready to run with Bundler support, which is the strongly recommended approach.
Complete documentation appears at https://www.ajyl.org/liquidoc/manual. It can be built locally using LiquiDoc itself.
-
Get the source.
git clone git@github.com:DocOps/liquidoc-gem.git cd liquidoc-gem bundle install -
Build the docs.
-
For a single-page HTML edition:
bundle exec asciidoctor docs/index.adoc -o docs/liquidoc-manual.html -
If you prefer a PDF edition, use:
bundle exec asciidoctor -r pdf docs/index.adoc -o docs/liquidoc-manual.pdf open docs/liquidoc-manual.pdf
-
-
Open the new file in your preferred browser or PDF reader
The instructions that formerly stood here have been used to the official LiquiDoc Admin and User Manual.
The instructions that formerly stood here have been used to the official LiquiDoc Admin and User Manual.
I get that this is the least sexy tool anyone has ever built. I truly do.
Except I kind of disagree. To me, it’s one of the most elegant ideas I’ve ever worked on, and I actually adore it.
Maybe it’s due to my love of flat files. The simplicity of anything in / anything out for plaintext files is such a holy grail in my mind. I am a huge fan of the universal converter Pandoc, which has saved me countless hours of struggle.
I totally dig markup languages and dynamic template engines, both of which I’ve been using to build cool shit for about 20 years. These form the direct sublayers of everything done with textual content in computing, and I want to help others play in the sandbox of dynamic markup.
You don’t have to love LiquiDoc to use it, or even to contribute. But if you get what I’m trying to do, give a holler.
The reason I’m developing LiquiDoc is to most flexibly handle common single-sourcing challenges posed by divergent output needs. I intend to experiment with other toolchains, datasource types, and template engines, but the point of this utility is to pull together great technologies to solve tough, recurring problems.
Contributions are very welcome.
This repo is maintained by the former Technical Documentation Manager at Rocana (formerly ScalingData, now mostly acquired by Splunk), which is the original copyright holder of LiquiDoc. I am teaching myself basic Ruby scripting just to code LiquiDoc and related tooling. Therefore, instructional pull requests are encouraged. I have no ego around the code itself. I know this isn’t the best, most consistent Ruby scripting out there, and I confess I’m more interested in what the tool does than how it does it. Help will be appreciated.
That said, because this utility is also made to go along with my book Codewriting, I prefer not to overcomplicate the source code, as I want relative beginners to be able to intuitively follow and maybe even modify it. I guess by that I mean, I’m resisting over-abstracting the source — I must be the beginner I have in mind.
I am very eager to collaborate, and I actually have extensive experience with collective authorship and product design, but I’m not a very social programmer. If you want to contribute to this tool, please get in touch. A pull request is a great way to reach out.
LiquiDoc originated under the copyright of Rocana, Inc, released under the MIT License. This fork is maintained by Brian Dominick, the original author. Rocana has been acquired by Splunk, but the author and driving maintainer of this tooling chose not to continue on with the rest of Rocana engineering, precisely in order to openly explore what tooling of this kind can do in various environments.
I am not sure if the copyright for the prime source transferred to Splunk, but it does not matter. This fork repository will be actively maintained by the original author, and my old coworkers and their new employer can make make use of my upgrades like everyone else.
|
📎
|
The LiquiDoc gem at rubygems.org has been published out of this repo starting with version 0.2.0. |
LiquiDoc and Codewriting author Brian Dominick is now available for contract work around implementation of advanced docs-as-code infrastructure. I am eager to work with engineering and support teams at software companies. I’m also seeking opportunities to innovate management of documentation and presentations at non-software organizations — especially if you’re working to make the world a better place! Check out codewriting.org for more info.