jekyll-generator-single-source

Installation

Add this line to your site's Gemfile:

group :jekyll_plugins do
  gem 'jekyll-generator-single-source'
end

Usage

Projects that have multiple products

Add these lines to your site's _config.yml:

jekyll-generator-single-source:
  versions_file: '<path_to_versions_file>.yml'
  docs_nav_folder: '<path_to_folder_containing_doc_nav_files'
  layout: 'docs-v2' # default value
  multiple_products: true # default value

The paths are relative to the site's source.

Example configuration:

jekyll-generator-single-source:
  versions_file: '_data/versions.yml'
  docs_nav_folder: '_data'

Projects with a single product

Add these lines to your site's _config.yml:

jekyll-generator-single-source:
  versions_file: '<path_to_versions_file>.yml'
  docs_nav_folder: '<path_to_folder_containing_doc_nav_files'
  layout: 'page'
  multiple_products: false
  base_dest_path: '<path_to_dest_folder_within_dist>'

Example configuration:

jekyll-generator-single-source:
  versions_file: '_data/versions.yml'
  docs_nav_folder: '_data'
  layout: 'page'
  multiple_products: false
  base_dest_path: 'docs'

Inheriting configuration

It is sometimes useful to inherit documentation from else where.

To do this you can set in your config:

inherit:
  path: /.repos/_src/
  nav: ../_src/.repos/_data/docs_nav_kuma_2.0.x.yml
  patches: [] # Array of modifications on your existing nav applied sequentially

patches identify the section of the docs with an array path which lists the title in the doc tree. For example if I have a doc:

items:
  - title: foo
    items:
      - text: bar
      - text: foo

I can use the path: [foo, bar] to modify this subsection of the docs.

There are currently 4 types of patches:

delete

Here's a patch to delete that bar subsection of the docs.

action: delete
path: [foo]
entries: [bar] # list of subsection to delete

The docs would look like:

items:
  - title: foo
    items:
      - text: foo

modify

Here's a patch to modify the foo section by changing the title.

action: modify
path: [foo]
title: foo2

The docs would look like:

items:
  - title: foo2
    items:
      - text: bar
      - text: foo

append

Add a subsection to the doc

action: append
path: [foo]
title: foo2

The docs would look like:

items:
  - title: foo
    items:
      - text: bar
      - text: foo
  - title: foo2

insert

Add a subsection to the doc

action: insert
path: [foo]
index: 1 # where to insert the entry (if negative inserts from the end)
text: foo2

The docs would look like:

items:
  - title: foo
    items:
      - text: bar
      - text: foo2
      - text: foo