6

I use Jekyll to create documentation for software products. I have 30 + different products that have a common LIQUID template but different content. Every single product documentation has its own table of content.

For one project, everything is OK. I have a content folder as well as css/js folders. I run "jekyll serve" and publish a project.

The problem is that, I do not want to have 30 Jekyll projects stored one next to another with similar css, configs, js folders and will only differ in content part.

The question is: how can I organize the internal structure so I have a single project with a common layout and 'x' different content folders inside the single project?

Like:

_product1/

  • some_subdir

    'topic.md'

_product2/

  • some_subdir

    'topic.md'

If it's possible, how can I then manage the output? I need to publish product 1 and product 2 ... product 'x' separately.

Thank you for the assistance.

UPD: Here is the demo project on GitHub: https://github.com/plywoods/JekyllDocumentationDemo

Andrey Langovoy
  • 795
  • 2
  • 7
  • 15
  • In the most recent Jekyll release, they added collections https://jekyllrb.com/docs/collections/ however it doesn't work for me at the moment. – Andrey Langovoy Jan 19 '18 at 10:50
  • Collections were the first thing i had in mind. What is the problem - i use them for the same purpose. – astark Jan 19 '18 at 11:14
  • @astark , thank you for replying. Inside my Jekyll project, I have created a folder that keeps all my collections. A single collection is one documentation project. Then in the config file, I indicated: collections_dir: folder_with_collections. In addition, I listed all my collections inside the Collections attribute of the config file. Now, I am trying to output any collection like: {% for item in site.collections %} – it doesn’t work for me. – Andrey Langovoy Jan 19 '18 at 12:43
  • Here is the discussion about where to declare collections_dir: my_collections: either inside collections or outside. collections_dir is a new feature relesed on JAN 2 2018 and it seems should be placed outside collections. http://talk.jekyllrb.com/t/how-all-collections-inside-one-subdirectory-works/1034/5 – Andrey Langovoy Jan 19 '18 at 13:02
  • @AndreyLangovoy Are products in any way related to each other? – Mario Nikolaus Feb 16 '18 at 08:29

1 Answers1

4

The way to have this content separation in Jekyll is through the use of Collections.

Here is an example of a Jekyll website using Collections: https://github.com/netponto/netponto.github.io

_meetings, _members, and _sessions are different collections and analogous to your _product1, _product2, etc.

You can customize the output / how the URL is going to be in the _config.yml of your Jekyll site. For example:

collections:
  meetings:
    output: true
    permalink: /reunioes/:path/
  sessions:
    output: true
    permalink: /sessoes/:path/

To display the items of a collection, for example the "sessions" collection, you do something like this:

{% for session in site.sessions %}
  <p>{{ session.title }}</p>
{% endfor %}

If you're having issues implementing the Collections, put together a reproducible example on GitHub, so that others can see what you've tried to do and point what's missing.

C. Augusto Proiete
  • 24,684
  • 2
  • 63
  • 91
  • Hi. Thank you for the assistance. Partially it works as you have described. However, there are many inconveniences (or I simply did not figure out yet). 1. The most recent release of Jekyll introduced the new feature that allows to keep all collections inside a single folder. To make Jekyll look for collections in that folder, I need to specify the following: collections_dir: folder_with_collections. Then I can’t make Jekyll display collections from that folder. 2. I thought I could manage the parts I want to output right in the config file simply declaring output: true or output: false. – Andrey Langovoy Jan 23 '18 at 10:52
  • Instead, I need to modify the layout file and place a specific product_name in the liquid loop. 3. Additionally. I have many collections with different content. The project contains only one common _images folder. Should it contain images for all collections? Is it possible to have a separate _image folder for each collection? 4. I have a common layout - header and footer are the same for each collection/project content. However, the header should contain the name of each project I build. To make this working I need to modify layout again. – Andrey Langovoy Jan 23 '18 at 10:53
  • 5. To make search working for each separate collection, I need to modify layout again. – Andrey Langovoy Jan 23 '18 at 10:53
  • `code` window.data = { {% for item in site.PROJECT_NAME %} {% if item.title %} {% unless item.excluded_in_search %} {% if added %},{% endif %} {% assign added = false %} "{{ item.url | slugify }}": { "id": "{{ item.url | slugify }}", "title": "{{ item.title | xml_escape }}", "category": "{{ collection.title | xml_escape }}", "url": " {{ item.url | xml_escape }}", "content": {{ item.content | strip_html | replace_regex: "[\s/\n]+"," " | strip | jsonify }} } – Andrey Langovoy Jan 23 '18 at 10:55
  • I am sorry abt the last one. I can't imagine how to format it correctly. – Andrey Langovoy Jan 23 '18 at 10:57
  • The main idea is that I need to make too much liquid layout modifications to output separate collections within a single layout. Why not simply declare output:true for required collection and output:false for those collections I want to skip in the output? Thank you. – Andrey Langovoy Jan 23 '18 at 10:59
  • @AndreyLangovoy Put together a reproducible example on GitHub, so that others can see what you've tried to do and point what's missing. – C. Augusto Proiete Jan 23 '18 at 19:29
  • please find the demo project here: https://github.com/plywoods/JekyllDocumentationDemo – Andrey Langovoy Jan 24 '18 at 10:52
  • did you have a chance to look the project on GitHub ? – Andrey Langovoy Feb 07 '18 at 12:28