LiquiDoc CMF V3 Bootstrap & Boilerplate

This PR releases version 3 of the LiquiDoc Content Management Framework.

* The Readme has been wholly upgraded, mostly for clarity but also in preparation for serving as source for external repos, notably the [WIP "LiquiDoc CMF Guides" project](https://github.com/DocOps/liquidoc-cmf).

* The comment-suppressed `jekyll` block of the boilerplate `Gemfile` has been uncommented and thus will install with `bundle install`/`bundle update` commands.

* Adds templates for initiating topics. The new commands generate a file with default/templated content as well as print to console a chunk of YAML for including in a `manifest.yml` file.

* Templatizes files that were in `_configs/` directory in V2, now built during init only.

* Lots of clarifying work in `data/meta.yml`.

* Clarifies bootstrapping instructions, which have been tested in multiple environments.

* Adds an HTML edition of the default document and tidied up the build.

* Huge thanks and ++ to @diggerlilly for thorough review under pressure. We're getting close to this thing being user friendly in the ways it deserves!

.gitignore

@@ -1,2 +1,3 @@
 build
 Gemfile.lock
+.DS_Store

Gemfile

@@ -12,7 +12,7 @@ group :asciidoctor_plugins do
   gem 'asciidoctor-diagram'
 end
 
-# gem 'jekyll'
-# group :jekyll_plugins do
-#   gem 'jekyll-asciidoc'
-# end
+gem 'jekyll'
+group :jekyll_plugins do
+  gem 'jekyll-asciidoc'
+end

_init/templates/init.yaml

@@ -0,0 +1,14 @@
+- action: parse
+  data:
+    file: data/meta.yml
+  builds:
+    - output: README.adoc
+      template: _init/templates/init_readme.asciidoc
+    - output: content/index.adoc
+      template: _init/templates/init_index.asciidoc
+    - output: {{project_config_dir}}/{{project_config_file}}
+      template: _init/templates/init_build-config.yaml
+    - output: {{project_config_dir}}/jekyll-global.yml
+      template: _init/templates/init_jekyll-global.yaml
+    - output: {{project_config_dir}}/asciidoctor.yml
+      template: _init/templates/init_asciidoctor.yaml

_configs/asciidoctor.yml → _init/templates/init_asciidoctor.yaml

@@ -1,4 +1,5 @@
 # This file contains global Asciidoctor attributes
 imagesdir: assets/images
+snippetsdir: ../snippets
 safe: 0
 icons: font

_init/templates/init_build-config.yaml

@@ -0,0 +1,35 @@
+# Move critical files to the temporary build directory
+- action: migrate
+  source: content/
+  target: _build/
+  options:
+    inclusive: false # Duplicate the files without the content/ dir
+- action: migrate
+  source: theme/
+  target: _build/
+# Prebuild includable files
+- action: parse
+  data: data/terms.yml
+  builds:
+    - output: _build/snippets/_built_terms.adoc
+      template: _templates/liquid/terms.asciidoc
+- action: parse
+  data: data/meta.yml
+  builds:
+    - output: _build/snippets/_built_company-info.adoc
+      template: _templates/liquid/company-info.asciidoc
+# Render your publication with Asciidoctor
+- action: render
+  source: _build/index.adoc
+  data:
+    - _configs/asciidoctor.yml
+    - data/meta.yml
+  builds:
+    - output: _build/docs/docs.html
+      doctype: book
+    - output: _build/docs/docs.pdf
+      doctype: book
+# Migrations in preparation for deploy
+- action: migrate
+  source: _build/assets/
+  target: _build/docs/

_init/templates/init_index.asciidoc

@@ -1,5 +1,17 @@
-= {{product_common_name}}
+= {{ product_suite_name }}
 
 == Maker Info
 
-include::includes/_built_company-info.adoc[]
+include::snippets/_built_company-info.adoc[]
+
+:leveloffset: +1
+
+include::pages/about.adoc[]
+
+include::topics/intro.adoc[]
+
+:leveloffset: -1
+
+= Appendices
+
+include::pages/jargon-guide.adoc[leveloffset=+1]

_init/templates/init_jekyll-global.yaml

@@ -0,0 +1,28 @@
+# This is the Jekyll configuration file
+title: {{product_suite_name}} Portals
+description: The documentation for {{project_subjects_list}}
+output: web
+source: {{project_build_dir}}
+host: 127.0.0.1
+port: {{local_serve_port}}
+destination: site
+
+data_dir:     data
+plugins_dir:  _plugins
+layouts_dir:
+includes_dir:
+images_dir:   assets/images
+css_dir:      theme/css
+theme_common_dir: theme
+js_dir: theme/js
+
+asciidoc: {}
+asciidoctor:
+  safe: 0
+  base_dir: :docdir
+# Do NOT place attributes here when building with LiquiDoc
+# They will be loaded from other external sources
+
+
+# File management
+encoding: "utf-8"

_init/templates/init_readme.asciidoc

@@ -1,48 +1,66 @@
-= {{product_common_name}} Documentation
-
-This documentation {{space_type}} uses a docs-as-code framework called link:https://github.com/briandominick/liquidoc-cmf[LiquiDoc CMF].
-Check it out for full instructions and links to demo projects.
+= {{ product_suite_name }} Documentation
+// This AsciiDoc file must be rendered to be properly viewed.
+// The easiest way to view it rendered is on GitHub at
+// https://github.com/DocOps/liquidoc-cmf
+// OR copy and paste these contents into
+// https://asciidoclive.com
+// BELOW is all AsciiDoc formatting:
+// https://asciidoctor.org/docs/what-is-asciidoc/
+//
+// Document attributes (variables)
+:docs_build_command_basic: bundle exec liquidoc -c {{ project_config_dir }}/{{ project_config_file }}
+//
+// Document content
+This documentation {{ space_type }} uses a docs-as-code framework called link:https://www.ajyl.org/liquidoc-cmf[LiquiDoc CMF].
 
 == Overview
 
 This is just a boilerplate stub to get you up and going.
 Describe your documentation project here.
 
-== Quickstart
+== Docs Build
+
+=== Requirements
+
+. Ruby runtime environment
+. Bundler package management for Ruby
+
+=== Quickstart
+
+This will get you up and running with our docs!
+
+==== Installation
+
 {% if space_type == "repo" %}
 . Clone this repo.
 +
-....
-git clone {{ git_repo_uri }}
-....
+[source,shell]
+----
+git clone {{ project_git_repo_origin_uri }} {{ project_root_dir }}
+----
 {% endif %}
-. Change to the proper directory.
+
+. Change to the proper working directory.
 +
-....
-cd {% if project_root %}{{ project_root }}{% else %}my_project{% endif %}{% if space_type == "directory" %}/{{ docs_root_path }}{% endif %}
-....
+[source,shell]
+----
+cd {{ project_root_dir }}{%if subj_rel == "folder" %}/{{ docs_root_path }}{% endif %}
+----
 
 . Run Bundler to install dependencies.
 +
-....
-bundle install
-....
+[source,shell]
+----
+bundle
+----
 +
 If Bundler is not installed, run `gem install bundler`, then repeat this command.
 
-. Run your first docs build.
-+
-....
-bundle exec liquidoc -c _configs/build-docs.yml
-....
-
-=== Requirements
-
-. Ruby runtime environment
-. Bundler package management for Ruby
-
-== Build
+==== Generation
 
-To build, run `bundle exec liquidoc -c _configs/build-docs.yml`.
+[source,shell,subs="+attributes"]
+----
+{docs_build_command_basic}
+----
 
-Check out the results in `_build/output/`.
+This procedure generates files in the `_build/docs/` directory.

_ops/init-topic.yml

@@ -0,0 +1,41 @@
+{%- assign slug_regex = "[a-z_\-]{7,50}" -%}
+{%- assign slug_regex_esc = "[a-z_\-]\{7,50\}" -%}
+{%- if vars.slug -%}
+  {%- assign slug_valid = vars.slug | regexreplace: slug_regex, "valid" -%}
+  {%- if slug_valid == "valid" -%}
+- action: parse
+  builds:
+    - template: _templates/liquid/ops/topic.asciidoc
+      output: content/topics/{{vars.slug}}.adoc
+      variables:
+        slug: {{vars.slug}}
+    {%- if vars.parent %}
+        parent: true
+    {% endif %}
+    - template: _templates/liquid/ops/topic-entry.yaml
+      output: stdout
+      variables:
+        slug: {{vars.slug}}
+    {%- if vars.title %}
+        title: {{vars.title}}
+    {% endif -%}
+    {%- if vars.parent %}
+        parent: {{vars.parent}}
+    {% endif -%}
+  {%- else -%}
+- action: parse
+  builds:
+    - template: _templates/liquid/ops/error.liquid
+      output: stdout
+      variables:
+        message: "Error: Slug must be between 7 and 50 characters and may only contain lowerase English letters, numerals, underscores (_), and hyphens (-)."
+  {%- endif -%}
+{% else %}
+# If we don't see a slug argument,
+- action: parse
+  builds:
+    - template: _templates/liquid/ops/error.liquid
+      output: stdout
+      variables:
+        message: "Error: You must provide arguments for slug and title! Aborting..."
+{% endif %}

_templates/liquid/company-info.asciidoc

@@ -1,3 +1,5 @@
 {company_name_official} +
 {company_address_street} +
 {company_address_city}, {company_address_state} {company_address_zipcode}
+
+image::company_logo_big.png[]

_templates/liquid/excludes.yaml

@@ -0,0 +1,23 @@
+# {% comment %}
+# This template builds a list of paths for Jekyll to ignore
+#
+# Expected parameters:
+# guide - (string) a guide slug, to indicate current guide
+# {% endcomment %}
+# File source: _templates/liquid/excludes.yaml
+# Informs Jekyll what not to render
+exclude:
+  - assets/
+  - theme/
+  - snippets/
+  - site/
+{% if vars.guide %}
+# Below this line all data is dynamically generated
+{% assign keep_topics = topics | where_exp: "item","item.guides contains vars.guide" -%}
+{%- assign keepers = keep_topics | map: "slug" -%}
+{%- for story in topics -%}
+{% unless keepers contains story.slug %}
+  - topics/{{ story.slug }}.adoc
+{%- endunless -%}
+{% endfor %}
+{% endif %}

_templates/liquid/ops/error.liquid

@@ -0,0 +1,5 @@
+{% if vars.message %}
+Whoops! {{vars.message}}
+{% else %}
+This error message lacks a 'message:'!
+{% endif %}

_templates/liquid/ops/topic-entry.yaml

@@ -0,0 +1,7 @@
+- slug: {{vars.slug}}
+  {%- if vars.title %}
+  title: {{vars.title}}
+  {%- endif -%}
+  {%- if vars.parent %}
+  subtopics:
+  {% endif -%}

_templates/liquid/ops/topic.asciidoc

@@ -0,0 +1,5 @@
+include::{topic_page_meta}[tags="{{vars.slug}}"]
+{%- if vars.parent %}
+
+include::../snippets/_built_container_{prod-slug}.adoc[tags="{{vars.slug}}"]
+{% endif -%}

_templates/liquid/page-meta.asciidoc

@@ -0,0 +1,21 @@
+{% assign these_topics = topics | where_exp: "item","item.guides contains vars.guide" %}
+{% for story in these_topics %}
+// tag::{{ story.slug }}[]
+{%- capture guides -%}
+{%- for r in story.guides -%}{{ r }}{%- unless forloop.last -%},{%- endunless -%}
+{%- endfor -%}{%- endcapture -%}
+{%- capture categories -%}
+{%- for c in story.categories -%}{{- c -}}{%- unless forloop.last -%},{%- endunless -%}
+{%- endfor -%}{%- endcapture -%}
+{%- capture tags -%}
+{%- for t in story.tags -%}{{ t }}{%- unless forloop.last -%},{%- endunless -%}
+{%- endfor -%}{%- endcapture %}
+= {{ story.title }}
+:page-title: {{ story.title }}
+:page-permalink: {guide_site_path}/{{ story.slug }}
+:page-guides: [{{ guides }}]
+:page-categories: [{{ categories }}]
+:page-tags: [{{ tags }}]
+// end::{{ story.slug }}[]
+
+{% endfor %}

_templates/liquid/sidebar.yaml

@@ -0,0 +1,29 @@
+# expects vars.guide from build-docs.yml
+{% assign guide = vars.guide %}
+entries:
+- title: Sidebar
+  levels: one
+  folders:
+{%- for cat in categories -%}
+{%- assign cat_found = false -%}
+{%- assign cat_topics = topics | where_exp:"item","item.categories contains cat" -%}
+{%- assign cat_role_topics = cat_topics | where_exp:"item","item.guides contains guide" -%}
+{%- for story in cat_role_topics -%}
+{%- unless cat_found -%}
+{%- assign cat_found = true %}
+    - title: {{ cat | capitalize }}
+      output: web
+      folderitems:
+{% if cat == "setup" %}
+        - title: Portal Overview
+          url: home
+          output: web
+{% endif -%}
+{%- endunless -%}
+{%- assign this_title = story.title -%}
+{%- if story.title_short -%}{%- assign this_title = story.title_short -%}{%- endif %}
+        - title: {{ this_title }}
+          url: {{ story.slug }}
+          output: web
+{% endfor -%}
+{%- endfor -%}