Getting Started with the Documentation Codebase

Whether you already had a Ruby runtime environment or just installed it, you’re now able to execute packaged Ruby scripts called “gems”. Gems can be executed via command-line interface or via LiquiDoc’s Ruby API, still under development. This means you can include LiquiDoc, Asciidoctor, or Jekyll into your own Ruby applications. The CLI also makes LiquiDoc available to any build or deployment utility that can work the command line.

Unless you intend to modify (hack) LiquiDoc, Asciidoctor, or Jekyll yourself, you don’t need to know anything about the Ruby language to use these utilities. However, it is handy to understand a little about how Ruby works on your system and how you will be engaging with it. That orientation starts below with Bundler, but first we should set the stage some more.

If you were not familiar with Git before, you are about to become intimate. We’ll be exploring Git operations in the LiquiDoc CMF Overview. For now, the relevant aspect of Git is that you have created a local Git repository during the first step above. This step executed a Git command (git clone) to grab a copy of this repo from the remote address and clone it to your system. In so doing, it initialized that root directory as a Git repository—​not just any set of files. This means your repository is ready for action, and all the powers of Git are at your fingertips. You’ll be using more of them soon enough.

Every LiquiDoc CMF project has a base directory from which it is best to run all commands. Always navigate into this directory when you begin working on content, so any liquidoc, asciidoctor, or jekyll commands you may find in these instructions are always run from that base.

The first Ruby “trick” you should be familiar with is bundle, the command that invokes the Bundler gem. For our purposes, Bundler reads the file simply called Gemfile, which you will find in your project root directory. Bundler gathers packages, primarily from Rubgems.org, an open-source gem package hosting service. This Gemfile defines dependencies used by LiquiDoc, Jekyll, and Asciidoctor as they process source code into publications during a build procedure. Engaging Bundler during every execution of these key Ruby gems ensures proper versions of all their prerequisites are in order.

Running bundle update on the command prompt will always check for and install the latest gem updates, which should be pretty safe to do from time to time.

The bundle exec liquidoc command executes the utility that coordinates the complex documentation build procedure. This is all instructed in the build-configuration file indicated in the command (_configs/build-docs.yml). We’ll explore that file and the entire build operation much further in the LiquiDoc CMF Overview.

At the end of this procedure, we have generated PDF artifacts as well as static HTML files completely parsed, compiled and ready to serve. You can always exclude either the PDF artifacts or the Jekyll portals from the build.

To skip the PDF build, use -v nopdf=true. To skip the Jekyll build, use -v nojekyll=true.

This step fires up a local “development server”, giving us a proper browser protocol for navigating all those HTML files. We look more deeply at the role Jekyll plays in LiquiDoc CMF in LiquiDoc CMF Overview.

This specific jekyll serve command was run with some special options. Without delving into too much detail, these options serve all the pages we want at once, for multiple portals, and disables default Jekyll features that would interfere with our operations.