You can get started with the LiquiDoc CMF environment used to document LiquiDoc and LiquiDoc CMF right away. This orientation will introduce you to the LiquiDoc/LDCMF docs codebase as well as its tooling, conventions, and workflow.
Your Role
As an LDCMF admin for your own project, you will have to at least initialize an LDCMF environment before building any docs or even sharing the environment with your team. This section will get you started, and the rest of this Guide will help you customize the environment to suit your product demands and your team’s workflow.
Once we make sure you have the few prerequisites in place, you can build these docs.
For more on your role as Administrator, see the
Installing Dependencies
This procedure invokes the LiquiDoc tool and in turn Asciidoctor, Jekyll, and other dependencies to build all documentation and other artifacts.
The only prerequisite software packages you may need are Ruby runtime and Git. You will also need a terminal application. The rest will be installed during the basic setup instructions.
Terminal
If you are a Linux user, hopefully you already know your favorite terminal.
For MacOS, use spotlight to find your terminal
, or try iTerm2.
Windows users should use the GitBash terminal installed the next step.
Git
If you are just getting started with Git, this GitHub resource guide may have something for your learning style.
For setting up Git on Windows, use the GitForWindows guide.
Ruby Runtime Environment
If you’re on Linux or MacOS, you probably have Ruby runtime.
Using your preferred terminal application, check your Ruby version with ruby -v
.
If you’re on Windows, use this download page. Ruby version must be 2.3.0 or higher; 2.5+ recommended, development kit not required.
Anne Gentle has provided excellent instructions for getting up and running on Windows with Ruby and Jekyll. (There are some good MacOS tips there as well.)
Quickstart
Open your preferred terminal, and navigate to a workspace in which you can create a new subdirectory for the local repository (“repo”).
-
Clone this repo.
git clone [email protected]:DocOps/liquidoc-cmf-guides.git liquidoc-cmf-guides
Now you have a local copy of the repository files.
-
Change your working directory to the docs directory.
Examplecd liquidoc-cmf-guides/
-
Run Bundler to install dependencies.
bundle install
If Ruby says you don’t have Bundler installed, run
gem install bundler
. -
Run your first build of these docs.
bundle exec liquidoc -c _configs/build-docs.yml
This executes a specific build routine using the LiquiDoc utility through Bundler, basing the build procedure on a config file.
-
Serve the website locally.
bundle exec jekyll serve --destination build/site \ --config _configs/jekyll-global.yml --skip-initial-build --no-watch
Now you’re able to view the LiquiDoc/LDCMF User Guides web portals and associated artifacts, right on your local machine. Browse http://127.0.0.1:{local_serve_port}.
Full Command
Use this command to execute a clean, build, and serve operation locally.
rm -rf _build && bundle exec liquidoc -c _configs/build-docs.yml && bundle exec jekyll serve --destination _build/site --config _configs/jekyll-global.yml --skip-initial-build
Special Build Options
Here are some special flags that work with this project’s primary build config (_configs/build-docs.yml
).
bundle exec liquidoc -c _configs/build-docs.yml -v norender=true
bundle exec liquidoc -c _configs/build-docs.yml -v nojekyll=true
bundle exec liquidoc -c _configs/build-docs.yml -v nopdf=true
What Just Happened?
The only steps you’ll need to perform regularly going forward will be the last two. But all these steps are relevant to your work, so we’ll exlore them one by one.
Ruby Runtime
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.
Git
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.
Project Working Directory
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.
If you ever need to know what directory you are in, enter pwd at the prompt and the full path will display.
|
Bundler
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.
LiquiDoc build procedure
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.
bundle exec liquidoc -c _configs/build-docs.yml -v nopdf=true
To skip the PDF build, use -v nopdf=true
.
To skip the Jekyll build, use -v nojekyll=true
.
Jekyll Serve Procedure
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.
The reason we have to run this step separately is that the build we performed in the last step created multiple Jekyll sites (our “portals”), and we have to serve Jekyll with specific commands in order to deploy the artifacts together. This step will be integrated into the LiquiDoc configuration when LiquiDoc is better able to accommodate complex Jekyll commands. |