From f5e6573e16f160f7e4447ed688b197db0577487a Mon Sep 17 00:00:00 2001
From: Silvio Giebl <silvio.giebl@hivemq.com>
Date: Wed, 25 Mar 2020 00:23:17 +0100
Subject: [PATCH] Removed unnecessary rake command and files Improved search
documentation
---
Rakefile | 1 -
_config.yml | 16 +++++----
bin/just-the-docs | 16 ---------
docs/configuration.md | 13 +++----
docs/search.md | 84 ++++++++++++++++++++++++++++---------------
lib/tasks/search.rake | 27 --------------
6 files changed, 71 insertions(+), 86 deletions(-)
delete mode 100644 Rakefile
delete mode 100755 bin/just-the-docs
delete mode 100644 lib/tasks/search.rake
diff --git a/Rakefile b/Rakefile
deleted file mode 100644
index b8b42c4b..00000000
--- a/Rakefile
+++ /dev/null
@@ -1 +0,0 @@
-Dir.glob('lib/tasks/*.rake').each {|r| import r}
diff --git a/_config.yml b/_config.yml
index 5979283b..5f7e9d85 100644
--- a/_config.yml
+++ b/_config.yml
@@ -19,18 +19,19 @@ baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com
permalink: pretty
-exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
+exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "README.md"]
# Set a path/url to a logo that will be displayed instead of the title
#logo: "/assets/images/just-the-docs.png"
# Enable or disable the site search
+# Supports true (default) or false
search_enabled: true
search:
- # Split documents into sections that can be individually searched
+ # Split pages into sections that can be searched individually
# Supports 1 - 6, default: 2
heading_level: 2
- # Maximum amount of previews to display
+ # Maximum amount of previews per search result
# Default: 3
previews: 3
# Maximum amount of words to display before a matched word in the preview
@@ -39,12 +40,13 @@ search:
# Maximum amount of words to display after a matched word in the preview
# Default: 10
preview_words_after: 10
- # Include the relative url in the search
- # Supports true (default) or false
- rel_url: false
- # Enable support for hyphenated search words
+ # Set the search token separator
# Default: /[\s\-/]+/
+ # Example: enable support for hyphenated search words
tokenizer_separator: /[\s/]+/
+ # Display the relative url in search results
+ # Supports true (default) or false
+ rel_url: false
# Enable or disable the search button
# Supports true or false (default)
button: true
diff --git a/bin/just-the-docs b/bin/just-the-docs
deleted file mode 100755
index 5a622903..00000000
--- a/bin/just-the-docs
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/usr/bin/env ruby
-
-gem_dir = File.expand_path("..",File.dirname(__FILE__))
-$LOAD_PATH.unshift gem_dir # Look in gem directory for resources first.
-exec_type = ARGV[0]
-
-if exec_type == 'rake' then
- require 'rake'
- require 'pp'
- pwd=Dir.pwd
- Dir.chdir(gem_dir) # We'll load rakefile from the gem's dir.
- Rake.application.init
- Rake.application.load_rakefile
- Dir.chdir(pwd) # Revert to original pwd for any path args passed to task.
- Rake.application.invoke_task(ARGV[1])
-end
diff --git a/docs/configuration.md b/docs/configuration.md
index 47d9106f..f9170fa7 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -37,10 +37,10 @@ logo: "/assets/images/just-the-docs.png"
search_enabled: true
search:
- # Split documents into sections that can be individually searched
+ # Split pages into sections that can be searched individually
# Supports 1 - 6, default: 2
heading_level: 2
- # Maximum amount of previews to display
+ # Maximum amount of previews per search result
# Default: 3
previews: 3
# Maximum amount of words to display before a matched word in the preview
@@ -49,12 +49,13 @@ search:
# Maximum amount of words to display after a matched word in the preview
# Default: 10
preview_words_after: 10
- # Include the relative url in the search
- # Supports true (default) or false
- rel_url: false
- # Enable support for hyphenated search words
+ # Set the search token separator
# Default: /[\s\-/]+/
+ # Example: enable support for hyphenated search words
tokenizer_separator: /[\s/]+/
+ # Display the relative url in search results
+ # Supports true (default) or false
+ rel_url: false
# Enable or disable the search button
# Supports true or false (default)
button: true
diff --git a/docs/search.md b/docs/search.md
index 35567863..32732b2c 100644
--- a/docs/search.md
+++ b/docs/search.md
@@ -15,62 +15,88 @@ nav_order: 7
---
-Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. All search results are shown in an auto-complete style interface (there is no search results page). By default, all generated HTML pages are indexed using the following data points:
+Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
+All search results are shown in an auto-complete style interface (there is no search results page).
+By default, all generated HTML pages are indexed using the following data points:
- Page title
- Page content
- Page URL
-## Set up search
+## Enable search in configuration
-### Generate search index
-
-Before you can use search, you must initialize the feature by running this `rake` command that comes with `just-the-docs`:
+In your site's `_config.yml`, enable search:
-```bash
-$ bundle exec just-the-docs rake search:init
+```yaml
+# Enable or disable the site search
+# Supports true (default) or false
+search_enabled: true
```
-This command creates the `search-data.json` file that Jekyll uses to create your search index. Alternatively, you can create the file manually in the `assets/js/` directory of your Jekyll site with this content:
+### Search granularity
-```liquid
-{% raw %}---
----
-{
- {% assign comma = false %}
- {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
- "title": "{{ page.title | replace: '&', '&' }}",
- "content": "{{ page.content | markdownify | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '</ul', ' . </ul' | replace: '</tr', ' . </tr' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | strip_html | escape_once | remove: 'Table of contents' | remove: '```' | remove: '---' | replace: '\', ' ' | replace: ' . . . ', ' . ' | replace: ' . . ', ' . ' | normalize_whitespace }}",
- "url": "{{ page.url | absolute_url }}",
- "relUrl": "{{ page.url }}"
- }{% assign comma = true %}
- {% endif %}{% endfor %}
-}{% endraw %}
-```
+Pages are split into sections that can be searched individually.
+The sections are defined by the headings on the page.
+Each section is displayed in a separate search result.
-_Note: If you don't run this rake command or create this file manually, search will not work (or it will use the search index data from this docs site, not your site's content)._
+```yaml
+# Split pages into sections that can be searched individually
+# Supports 1 - 6, default: 2
+search.heading_level: 2
+```
-### Enable search in configuration
+### Search previews
-In your site's `_config.yml`, enable search:
+A search result can contain previews that show where the search words are found in the specific section.
```yaml
-# Enable or disable the site search
-search_enabled: true
+# Maximum amount of previews per search result
+# Default: 3
+search.previews: 3
+
+# Maximum amount of words to display before a matched word in the preview
+# Default: 5
+search.preview_words_before: 5
+
+# Maximum amount of words to display after a matched word in the preview
+# Default: 10
+search.preview_words_after: 10
```
+### Search tokenizer
+
The default is for hyphens to separate tokens in search terms:
`gem-based` is equivalent to `gem based`, matching either word.
To allow search for hyphenated words:
```yaml
# Set the search token separator
-search_tokenizer_separator: /[\s/]+/
+# Default: /[\s\-/]+/
+# Example: enable support for hyphenated search words
+search.tokenizer_separator: /[\s/]+/
+```
+
+### Display URL in search results
+
+```yaml
+# Display the relative url in search results
+# Supports true (default) or false
+search.rel_url: false
+```
+
+### Display search button
+
+```yaml
+# Enable or disable the search button
+# Supports true or false (default)
+search.button: true
```
+
## Hiding pages from search
-Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page. To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
+Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page.
+To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
#### Example
{: .no_toc }
diff --git a/lib/tasks/search.rake b/lib/tasks/search.rake
deleted file mode 100644
index 82dcfb6c..00000000
--- a/lib/tasks/search.rake
+++ /dev/null
@@ -1,27 +0,0 @@
-namespace :search do
- desc 'Generate the files needed for search functionality'
- task :init do
- puts 'Creating search data json file...'
- mkdir_p 'assets/js'
- touch 'assets/js/search-data.json'
- content = %Q[{{ page.content | markdownify | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '</ul', ' . </ul' | replace: '</tr', ' . </tr' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | strip_html | escape_once | remove: 'Table of contents' | remove: '```' | remove: '---' | replace: '\', ' ' | replace: ' . . . ', ' . ' | replace: ' . . ', ' . ' | normalize_whitespace }}]
- puts 'Done.'
- puts 'Generating content...'
-
- File.open('assets/js/search-data.json', 'w') do |f|
- f.puts '---
----
-{
- {% assign comma = false %}
- {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
- "title": "{{ page.title | replace: '&', '&' }}",
- "content": "'+content+'",
- "url": "{{ page.url | absolute_url }}",
- "relUrl": "{{ page.url }}"
- }{% assign comma = true %}
- {% endif %}{% endfor %}
-}'
- end
- puts 'Done.'
- end
-end
--
GitLab