/liquidoc-gem

The canonical gem source for LiquiDoc, a ruby-based documentation parsing and rendering utility enabling advanced builds with Asciidoctor, Jekyll, Liquid, and semi-structured data files.

Primary LanguageRubyMIT LicenseMIT

LiquiDoc

LiquiDoc is a documentation build utility for true single-sourcing of technical content and data in a Jekyll/Asciidoctor-based toolchain. It is especially suited for documentation projects with various required output formats from complex, single-sourced codebases.

Broadly, LiquiDoc is intended for any project that generates technical content for use in documentation, user interfaces, and even back-end code. The highly configurable command-line utility (and fledgling Ruby gem) engages the Liquid template engine to parse complex data into rich text output.

Data sources can be flat files in XML, JSON, CSV, and our preferred human-editable format: YAML. LiquiDoc can ingest semi-structured data from any plaintext file by pattern matching with regular expressions.

LiquiDoc can further coordinate build operations, including rendering static websites using Jekyll and Asciidoctor, but these dependencies are likely to become optional by the 1.0 release.

Table of Contents

Installation

Your system must be running Ruby 2.3 or later (2.6+ recommended). See rubyinstaller.org if you’re on Windows, or preferably use Microsoft’s Windows Subsystem for Linux on Windows 10 or 11, then follow as a Linux user.

We strongly recommend all MacOS and Linux users employ a Ruby package manager like rbenv (preferred) or or RVM.

💡
 The fastest way to install is by running gem install liquidoc, but we strongly recommend using Bundler to manage all Ruby dependencies.

  1. Create a file called Gemfile in your project’s root directory.

  2. Populate the file with LiquiDoc dependencies.

    A LiquiDoc project Gemfile
    source 'https://rubygems.org'

gem 'liquidoc'

  3. Open a terminal (command prompt).

    If you don’t have a preferred terminal application, use your OS’s magic search and look for terminal.

  4. Navigate to your project root directory.

    Example
    cd Documents/workspace/my_project

  5. Run bundle install to prepare dependencies.

    If you do not have Bundler installed, Ruby will tell you. Enter gem install bundler, let Bundler install, then repeat this step.

LiquiDoc should now be ready to run with Bundler support, which is the strongly recommended approach.

Documentation

The complete documentation for any version of LiquiDoc can be built locally using LiquiDoc itself.

  1. Get the source.

    git clone git@github.com:DocOps/liquidoc-gem.git
cd liquidoc-gem/_docs
bundle install

  2. Build the docs.

    bundle exec liquidoc -c _ops/build-docs.yml

  3. Open the new files from _build/artifacts/ in your preferred browser or PDF reader

Usage

The documentation that formerly stood here has been moved to the LiquiDoc Admin and User Manual and Liquid Filters API Reference.

Contributing

Contributions are very welcome. If you want to contribute to this tool, please get in touch. A pull request is a great way to reach out.

Licensing

LiquiDoc originated under the copyright of Rocana, Inc, released under the MIT License in 2017. This fork is maintained by Brian Dominick, the original author.