Browse Source

Merge pull request #379 from SgtSilvio/feature/doc-collections

Feature/doc collections
pull/1/head
Patrick Marsceill 2 years ago
committed by GitHub
parent
commit
6be8a2e38a
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
  1. 4
      _includes/nav.html
  2. 17
      _layouts/default.html
  3. 23
      _sass/navigation.scss
  4. 22
      assets/js/zzzz-search-data.json
  5. 48
      docs/configuration.md
  6. 22
      lib/tasks/search.rake

4
_includes/nav.html

@ -1,6 +1,6 @@
<ul class="nav-list">
{%- assign ordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order != nil" -%}
{%- assign unordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order == nil" -%}
{%- assign ordered_pages_list = include.pages | where_exp:"item", "item.nav_order != nil" -%}
{%- assign unordered_pages_list = include.pages | where_exp:"item", "item.nav_order == nil" -%}
{%- if site.nav_sort == 'case_insensitive' -%}
{%- assign sorted_ordered_pages_list = ordered_pages_list | sort_natural:"nav_order" -%}
{%- assign sorted_unordered_pages_list = unordered_pages_list | sort_natural:"title" -%}

17
_layouts/default.html

@ -48,7 +48,22 @@ layout: table_wrappers
</a>
</div>
<nav role="navigation" aria-label="Main" id="site-nav" class="site-nav">
{% include nav.html %}
{% if site.just_the_docs.collections %}
{% assign collections_size = site.just_the_docs.collections | size %}
{% for collection_entry in site.just_the_docs.collections %}
{% assign collection_key = collection_entry[0] %}
{% assign collection_value = collection_entry[1] %}
{% assign collection = site[collection_key] %}
{% if collection_value.nav_exclude != true %}
{% if collections_size > 1 %}
<div class="nav-category">{{ collection_value.name }}</div>
{% endif %}
{% include nav.html pages=collection %}
{% endif %}
{% endfor %}
{% else %}
{% include nav.html pages=site.html_pages %}
{% endif %}
</nav>
<footer class="site-footer">
This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.

23
_sass/navigation.scss

@ -131,6 +131,29 @@
}
}
.nav-category {
padding-top: $sp-2;
padding-right: $gutter-spacing-sm;
padding-bottom: $sp-2;
padding-left: $gutter-spacing-sm;
font-weight: 600;
text-align: end;
text-transform: uppercase;
border-bottom: $border $border-color;
@include fs-2;
@include mq(md) {
padding-right: $gutter-spacing;
padding-left: $gutter-spacing;
margin-top: $gutter-spacing-sm;
text-align: start;
&:first-child {
margin-top: 0;
}
}
}
// Aux nav
.aux-nav {

22
assets/js/zzzz-search-data.json

@ -2,8 +2,21 @@
permalink: /assets/js/search-data.json
---
{
{%- assign i = 0 -%}
{% for page in site.html_pages %}
{%- assign i = 0 -%}
{%- assign pages_array = '' | split: '' -%}
{%- assign pages_array = pages_array | push: site.html_pages -%}
{%- if site.just_the_docs.collections -%}
{%- for collection_entry in site.just_the_docs.collections -%}
{%- assign collection_key = collection_entry[0] -%}
{%- assign collection_value = collection_entry[1] -%}
{%- assign collection = site[collection_key] -%}
{%- if collection_value.search_exclude != true -%}
{%- assign pages_array = pages_array | push: collection -%}
{%- endif -%}
{%- endfor -%}
{%- endif -%}
{%- for pages in pages_array -%}
{%- for page in pages -%}
{%- if page.title and page.search_exclude != true -%}
{%- assign page_content = page.content -%}
{%- assign heading_level = site.search.heading_level | default: 2 -%}
@ -14,7 +27,7 @@ permalink: /assets/js/search-data.json
{%- endfor -%}
{%- assign parts = page_content | split: '<h1' -%}
{%- assign title_found = false -%}
{% for part in parts offset: 1 %}
{%- for part in parts offset: 1 -%}
{%- assign titleAndContent = part | split: '</h1>' -%}
{%- assign title = titleAndContent[0] | replace_first: '>', '<h1>' | split: '<h1>' -%}
{%- assign title = title[1] | strip_html -%}
@ -54,5 +67,6 @@ permalink: /assets/js/search-data.json
{%- assign i = i | plus: 1 -%}
{%- endunless -%}
{%- endif -%}
{% endfor %}
{%- endfor -%}
{%- endfor %}
}

48
docs/configuration.md

@ -22,6 +22,54 @@ Just the Docs has some specific configuration parameters that can be defined in
View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
## Document collections
By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
For example, put all your documentation files in the `_docs` folder and create the `docs` collection:
```yaml
# Define Jekyll collections
collections:
# Define a collection named "docs", its documents reside in the "_docs" directory
docs:
permalink: "/:collection/:path/"
output: true
just_the_docs:
# Define which collections are used in just-the-docs
collections:
# Reference the "docs" collection
docs:
# Give the collection a name
name: Documentation
# Exclude the collection from the navigation
# Supports true or false (default)
nav_exclude: false
# Exclude the collection from the search
# Supports true or false (default)
search_exclude: false
```
You can reference multiple collections.
This creates categories in the navigation with the configured names.
```yaml
collections:
docs:
permalink: "/:collection/:path/"
output: true
tutorials:
permalink: "/:collection/:path/"
output: true
just_the_docs:
collections:
docs:
name: Documentation
tutorials:
name: Tutorials
```
## Site logo
```yaml

22
lib/tasks/search.rake

@ -12,8 +12,21 @@ namespace :search do
permalink: /assets/js/search-data.json
---
{
{%- assign i = 0 -%}
{% for page in site.html_pages %}
{%- assign i = 0 -%}
{%- assign pages_array = '' | split: '' -%}
{%- assign pages_array = pages_array | push: site.html_pages -%}
{%- if site.just_the_docs.collections -%}
{%- for collection_entry in site.just_the_docs.collections -%}
{%- assign collection_key = collection_entry[0] -%}
{%- assign collection_value = collection_entry[1] -%}
{%- assign collection = site[collection_key] -%}
{%- if collection_value.search_exclude != true -%}
{%- assign pages_array = pages_array | push: collection -%}
{%- endif -%}
{%- endfor -%}
{%- endif -%}
{%- for pages in pages_array -%}
{%- for page in pages -%}
{%- if page.title and page.search_exclude != true -%}
{%- assign page_content = page.content -%}
{%- assign heading_level = site.search.heading_level | default: 2 -%}
@ -24,7 +37,7 @@ permalink: /assets/js/search-data.json
{%- endfor -%}
{%- assign parts = page_content | split: \'<h1\' -%}
{%- assign title_found = false -%}
{% for part in parts offset: 1 %}
{%- for part in parts offset: 1 -%}
{%- assign titleAndContent = part | split: \'</h1>\' -%}
{%- assign title = titleAndContent[0] | replace_first: \'>\', \'<h1>\' | split: \'<h1>\' -%}
{%- assign title = title[1] | strip_html -%}
@ -64,7 +77,8 @@ permalink: /assets/js/search-data.json
{%- assign i = i | plus: 1 -%}
{%- endunless -%}
{%- endif -%}
{% endfor %}
{%- endfor -%}
{%- endfor %}
}'
end
puts 'Done.'

Loading…
Cancel
Save