// This AsciiDoc file must be rendered to be properly viewed. // The easiest way to view it rendered is on BitBucket // OR copy and paste these contents into // https://asciidoclive.com // BELOW is all AsciiDoc formatting: // https://asciidoctor.org/docs/what-is-asciidoc/
// THESE ATTRIBUTES ARE FOR THE README file specifically // They will be replaced in the main build by data from // data/meta.yml and other files = LiquiDoc // tag::settings[] :xref_source-markup-liquid-basics: liquid-templating :xref_build-config-dynamic: dynamic-config :ldops_url: https://github.com/DocOps/liquidoc-ops/ :docops_site_url: https://www.docops.org :docops_docs_url: https://docs.docops.org :liquidoc_portal_url: {docops_site_url}/liquidoc :liquidoc_manual_url: {docops_docs_url}/liquidoc-user-manual.html // end::settings[] :show_admin: true :toc: macro :toclevels: 3 ifndef::env-github[:icons: font] ifdef::env-github[] :status: :outfilesuffix: .adoc :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[]
// tag::overview[] 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.
ifndef::env-github[] [NOTE] LiquiDoc's prime source is on link:https://github.com/DocOps/liquidoc-gem[icon:github[] Github]. + Use the Issues feature for support requests.
ifdef::vrsn[]
[NOTE]
This manual covers LiquiDoc version {vrsn}.x.
endif::[]
endif::[]
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.
ifndef::manual[] toc::[] endif::[] // end::overview[]
// tag::installation[] == Installation
// tag::ruby-install-notice[] Your system must be running Ruby 2.3 or later (2.6+ recommended). See https://rubyinstaller.org/downloads[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 link:https://github.com/rbenv/rbenv[rbenv] (preferred) or or link:https://rvm.io/[RVM].
// end::ruby-install-notice[]
[TIP]
The fastest way to install is by running gem install liquidoc, but we strongly recommend using Bundler to manage all Ruby dependencies.
. Create a file called Gemfile in your project's root directory.
source 'https://rubygems.org'
. Open a terminal (command prompt).
+
If you don't have a preferred terminal application, use your OS's magic search and look for terminal.
. 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. // end::installation[]
== Documentation
Current versions of the link:{liquidoc_manual_url}[LiquiDoc Admin and User Manual] and link:{docops_docs_url}/liquidoc-liquid-api.html[Liquid Filters API Reference].
The complete documentation for any version of LiquiDoc can be built locally using LiquiDoc itself.
. Build the docs. + bundle exec liquidoc -c _ops/build-docs.yml
. 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 link:{liquidoc_manual_url}[LiquiDoc Admin and User Manual] and link:{docops_docs_url}/liquidoc-liquid-api.html[Liquid Filters API Reference].
=== Contributing // tag::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. // end::contributing[]
=== Licensing // tag::licensing[] LiquiDoc link:https://github.com/scalingdata/liquidoc-gem[originated] under the copyright of Rocana, Inc, released under the MIT License in 2017. This fork is maintained by Brian Dominick, the original author. // tag::licensing[]