diff --git a/_docs/Gemfile.lock b/_docs/Gemfile.lock index 9f6d1d5..afcd07a 100644 --- a/_docs/Gemfile.lock +++ b/_docs/Gemfile.lock @@ -80,6 +80,10 @@ GEM rb-inotify (~> 0.9, >= 0.9.10) logger (1.4.3) mercenary (0.4.0) + mini_portile2 (2.6.1) + nokogiri (1.12.5) + mini_portile2 (~> 2.6.1) + racc (~> 1.4) nokogiri (1.12.5-x86_64-linux) racc (~> 1.4) pathutil (0.16.2) @@ -128,6 +132,7 @@ GEM word_wrap (1.0.0) PLATFORMS + ruby x86_64-linux DEPENDENCIES diff --git a/_docs/_builds/snippets/includes_dirs_list.adoc b/_docs/_builds/snippets/includes_dirs_list.adoc new file mode 100644 index 0000000..90d98de --- /dev/null +++ b/_docs/_builds/snippets/includes_dirs_list.adoc @@ -0,0 +1,2 @@ + +{"liquidoc"=>[{"dirs"=>"'_templates','_templates/liquid','_templates/liquid/ops','_templates/ops','theme/_includes','theme/_layouts'"}]} diff --git a/_docs/_ops/build-docs.yml b/_docs/_ops/build-docs.yml index c08b71d..975c9c4 100644 --- a/_docs/_ops/build-docs.yml +++ b/_docs/_ops/build-docs.yml @@ -11,6 +11,18 @@ builds: - output: _build/data/built/version.yml template: _templates/version.yaml +- action: parse + data: + file: ../lib/liquidoc.rb + type: regex + pattern: '^\@includes_dirs_def\s\=\s\[(?.*)\]' + builds: + - output: _build/data/built/includes_dirs.json +- action: parse + data: _build/data/built/includes_dirs.json + builds: + - output: _build/snippets/built/includes-dirs-list.adoc + template: _templates/includes-dirs-list.asciidoc - action: render source: index.adoc data: diff --git a/_docs/_templates/includes-dirs-list.asciidoc b/_docs/_templates/includes-dirs-list.asciidoc new file mode 100644 index 0000000..c713763 --- /dev/null +++ b/_docs/_templates/includes-dirs-list.asciidoc @@ -0,0 +1,4 @@ +{%- assign list = data.liquidoc[0]['dirs'] | replace:"'","" | split:"," %} +{%- for item in list %} +* `{{ item }}` +{%- endfor %} diff --git a/_docs/topics/reference.adoc b/_docs/topics/reference.adoc index e01c4f7..a9efe8b 100644 --- a/_docs/topics/reference.adoc +++ b/_docs/topics/reference.adoc @@ -108,6 +108,12 @@ s| variables | N/A | N/A +s| includes_dirs +| Optional +| N/A +| N/A +| N/A + s| properties | N/A | N/A diff --git a/_docs/topics/templating_liquid.adoc b/_docs/topics/templating_liquid.adoc index 3e18c7a..b7acdea 100644 --- a/_docs/topics/templating_liquid.adoc +++ b/_docs/topics/templating_liquid.adoc @@ -202,6 +202,35 @@ LiquiDoc does not have an equivalent of https://jekyllrb.com/docs/liquid/tags/#c For now, we will leave Liquid's core tags best documented in Shopify's https://shopify.github.io/liquid/[official Liquid documentation], as augmented by their https://github.com/shopify/liquid/wiki/Liquid-for-Designers[Liquid for Designers]. Ignore all of Jekyll's tag documentation when working on LiquiDoc templates, in favor of the following. +.Designating Alternate Includes Source Directories +**** +For templates that employ the Liquid `include` tag to transclude additional template files, LiquiDoc trawls certain directories in search of the named template. + +By default, LiquiDoc will check the following paths for a template with the indicated filename: + +include::../_build/snippets/built/includes-dirs-list.adoc[] + +Additionally, the directory of the primary template will be appended to this list, so LiquiDoc will always scan the calling template's own directory first for a matching file. + +To override the default list, add the `includes_dirs` property to the `build` block. + +.Example -- Custom includes paths +[source,yaml] +---- +- action: parse + data: mydata.yml + builds: + - output: _build/myoutput.txt + template: _extras/mytemplate.text + includes_dirs: + - _includes + - _build/_includes +---- + +In the above example, assuming `mytemplate.text` contains one or more `include` tags, the directories `+++_includes/+++` and `+++_build/_includes/+++` will be checked _instead of_ the default directories. +The main template's home directory (`_extras/`) will also be checked. +**** + === Filters LiquiDoc is proud to offer the largest set of Liquid filters available in one place. diff --git a/lib/liquid/tags/jekyll.rb b/lib/liquid/tags/jekyll.rb index 0e94ab1..41fab13 100644 --- a/lib/liquid/tags/jekyll.rb +++ b/lib/liquid/tags/jekyll.rb @@ -112,13 +112,14 @@ def render_variable(context) # Array of directories where includes are stored def tag_includes_dirs(context) - # context[:includes_dirs] - ['_templates','_templates/liquid','_templates/liquid/ops','theme/_includes','_theme/layouts'] + context.stack do + context['includes_dirs'] + end end # Traverse includes dirs, setting paths for includes def locate_include_file(context, file, safe) - includes_dirs = ['_templates','_templates/liquid','_templates/liquid/ops','_templates/ops','theme/_includes','theme/_layouts'] + includes_dirs = self.tag_includes_dirs(context) includes_dirs.each do |dir| path = File.join(dir.to_s, file.to_s) return path if File.exist?(path) diff --git a/lib/liquidoc.rb b/lib/liquidoc.rb index 83969c1..a260328 100755 --- a/lib/liquidoc.rb +++ b/lib/liquidoc.rb @@ -42,7 +42,7 @@ @build_dir = @build_dir_def @configs_dir = @base_dir + '_configs' @templates_dir = @base_dir + '_templates/' -@includes_dirs_def = ['.','_templates','_templates/liquid','_templates/liquid/ops','_templates/ops','theme/_includes','_theme/layouts'] +@includes_dirs_def = ['_templates','_templates/liquid','_templates/liquid/ops','_templates/ops','theme/_includes','theme/_layouts'] @includes_dirs = @includes_dirs_def @data_dir = @base_dir + '_data/' @data_files = nil @@ -155,7 +155,8 @@ def iterate_build cfg build.add_data!(build.variables, "vars") if build.variables includes_dirs = @includes_dirs includes_dirs = build.includes_dirs if build.includes_dirs - build.add_data!({:includes_dirs=>includes_dirs}) + includes_dirs.unshift(File.dirname(build.template)) + build.add_data!(includes_dirs: includes_dirs) liquify(build.data, build.template, build.output) # perform the liquify operation else # Prep & perform a direct conversion # Delete nested data and vars objects @@ -1636,7 +1637,7 @@ def to_json input @template_file = @base_dir + n end - opts.on("--includes PATH[,PATH]", "Paths to directories where includes (partials) can be found." ) do |n| + opts.on("--includes_dirs PATH[,PATH]", "Paths to directories where includes (partials) can be found. Overrides default directories." ) do |n| n = n.force_array # n.map { |p| @base_dir + p } @includes_dirs = @includes_dirs.concat n diff --git a/lib/liquidoc/version.rb b/lib/liquidoc/version.rb index c4523de..c534ef4 100644 --- a/lib/liquidoc/version.rb +++ b/lib/liquidoc/version.rb @@ -1,3 +1,3 @@ module Liquidoc - VERSION = "0.12.0" + VERSION = "0.12.1-rc1" end