From f0eb09aba52ac1b0af49a72f0bfa8f3a1edb0e85 Mon Sep 17 00:00:00 2001 From: Alex Earnshaw Date: Tue, 17 Sep 2019 12:01:37 +0100 Subject: [PATCH 1/4] Add config and doc for Algolia DocSearch --- userguide/config.toml | 7 +++- .../en/docs/Adding content/navigation.md | 33 +++++++++++++++++-- 2 files changed, 37 insertions(+), 3 deletions(-) diff --git a/userguide/config.toml b/userguide/config.toml index 012d7e1e7c..d2f7ec3af5 100644 --- a/userguide/config.toml +++ b/userguide/config.toml @@ -97,7 +97,10 @@ time_format_default = "January 2, 2006" rss_sections = ["blog"] # Google Custom Search Engine ID. Remove or comment out to disable search. -gcs_engine_id = "011217106833237091527:la2vtv2emlw" +#gcs_engine_id = "011217106833237091527:la2vtv2emlw" + +# Enable Algolia DocSearch +algolia_docsearch = true # User interface configuration [params.ui] @@ -105,6 +108,8 @@ gcs_engine_id = "011217106833237091527:la2vtv2emlw" sidebar_menu_compact = false # Set to true to disable breadcrumb navigation. breadcrumb_disable = false +# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) +sidebar_search_disable = true # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar navbar_logo = true diff --git a/userguide/content/en/docs/Adding content/navigation.md b/userguide/content/en/docs/Adding content/navigation.md index fcbf4f2395..eea52594ed 100644 --- a/userguide/content/en/docs/Adding content/navigation.md +++ b/userguide/content/en/docs/Adding content/navigation.md @@ -92,7 +92,7 @@ By default, the section menu will show the current section fully expanded all th Breadcrumb navigation is enabled by default. To disable breadcrumb navigation, set site param `ui.breadcrumb_disable = true` in `config.toml`. -## Configure search +## Configure GCSE search By default Docsy uses a [Google Custom Search Engine](https://cse.google.com/cse/all) to search your site. To enable this feature, you'll first need to make sure that you have built a public production version of your site, as otherwise your site won't be crawled and indexed. @@ -132,7 +132,7 @@ Once you have your search engine set up, you can add the feature to your site: gcs_engine_id = "011737558837375720776:fsdu1nryfng" ``` -### Disabling search +### Disabling GCSE search If you don't specify a Google Custom Search Engine ID for your project, the search box won't appear in your site. If you're using the default `config.toml` from the example site and want to disable search, just comment out or remove the relevant line. @@ -143,3 +143,32 @@ By default, the search box appears in both the top navigation bar and at the top ``` sidebar_search_disable = true ``` + +## Configure Algolia DocSearch + +As an alternative to GCSE, you can use [Algolia DocSearch](https://community.algolia.com/docsearch/) with this theme. Algolia DocSearch is free for public documentation sites. + +### Sign up for Algolia DocSearch + +Complete the form at [https://community.algolia.com/docsearch/#join-docsearch-program](https://community.algolia.com/docsearch/#join-docsearch-program). + +If you are accepted to the program, you will receive the JavaScript code to add to your documentation site from Algolia by email. + +### Adding Algolia DocSearch + +1. Enable Algolia DocSearch in `config.toml`. + + ``` + # Enable Algolia DocSearch + algolia_docsearch = true + ``` + +2. Remove or comment out any GCSE ID in `config.toml` as you can only have one type of search enabled. See [Disabling GCSE search](#disabling-gcse-search). + +3. Disable the sidebar search in `config.toml` as this is not currently supported for Algolia DocSearch. See [Disabling the sidebar search box](#disabling-the-sidebar-search-box). + +3. Add the JavaScript code provided to you by Algolia to the head and body of every page on your site. See [Add code to head or before body end](/docs/adding-content/lookandfeel/#add-code-to-head-or-before-body-end) for details. + +4. Update the `inputSelector` field in the body end Javascript with the appropriate CSS selector (e.g. `.td-search-input` to use the default CSS from this theme). + +When you've completed these steps the Algolia search should be enabled on your site. Search results are displayed as a drop-down under the search box, so you don't need to add any search results page. From 4b4dbef5bbb4d6328e52248809c3302c6bf6f9b1 Mon Sep 17 00:00:00 2001 From: Alex Earnshaw Date: Tue, 17 Sep 2019 12:06:49 +0100 Subject: [PATCH 2/4] Add config and doc for Algolia DocSearch --- layouts/partials/hooks/body-end.html | 9 +++++++++ layouts/partials/hooks/head-end.html | 2 ++ layouts/partials/search-input.html | 3 +++ 3 files changed, 14 insertions(+) diff --git a/layouts/partials/hooks/body-end.html b/layouts/partials/hooks/body-end.html index e69de29bb2..e03241f6c7 100644 --- a/layouts/partials/hooks/body-end.html +++ b/layouts/partials/hooks/body-end.html @@ -0,0 +1,9 @@ + + + \ No newline at end of file diff --git a/layouts/partials/hooks/head-end.html b/layouts/partials/hooks/head-end.html index e69de29bb2..44b65791c3 100644 --- a/layouts/partials/hooks/head-end.html +++ b/layouts/partials/hooks/head-end.html @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/layouts/partials/search-input.html b/layouts/partials/search-input.html index 883ca3c3a6..82125fd686 100644 --- a/layouts/partials/search-input.html +++ b/layouts/partials/search-input.html @@ -1,3 +1,6 @@ {{ with .Site.Params.gcs_engine_id }} +{{ end }} +{{ with .Site.Params.algolia_docsearch }} + {{ end }} \ No newline at end of file From b08245efab9a274c7fbcdb78545b537ab41faf29 Mon Sep 17 00:00:00 2001 From: Alex Earnshaw Date: Wed, 9 Oct 2019 13:37:18 +0100 Subject: [PATCH 3/4] add conditionals and test with axway javascript --- layouts/partials/hooks/body-end.html | 5 +++-- layouts/partials/hooks/head-end.html | 6 ++++-- layouts/partials/search-input.html | 5 +---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/layouts/partials/hooks/body-end.html b/layouts/partials/hooks/body-end.html index e03241f6c7..cff622b9f4 100644 --- a/layouts/partials/hooks/body-end.html +++ b/layouts/partials/hooks/body-end.html @@ -1,4 +1,4 @@ - +{{ with .Site.Params.algolia_docsearch }} \ No newline at end of file + +{{ end }} \ No newline at end of file diff --git a/layouts/partials/hooks/head-end.html b/layouts/partials/hooks/head-end.html index 44b65791c3..8dad9b8220 100644 --- a/layouts/partials/hooks/head-end.html +++ b/layouts/partials/hooks/head-end.html @@ -1,2 +1,4 @@ - - \ No newline at end of file +{{ with .Site.Params.algolia_docsearch }} + + +{{ end }} \ No newline at end of file diff --git a/layouts/partials/search-input.html b/layouts/partials/search-input.html index 82125fd686..ee82a69884 100644 --- a/layouts/partials/search-input.html +++ b/layouts/partials/search-input.html @@ -1,6 +1,3 @@ -{{ with .Site.Params.gcs_engine_id }} - -{{ end }} -{{ with .Site.Params.algolia_docsearch }} +{{ with or .Site.Params.gcs_engine_id .Site.Params.algolia_docsearch }} {{ end }} \ No newline at end of file From bbe2e8d945df392d33c07ad8d1f8ae21b807a404 Mon Sep 17 00:00:00 2001 From: Alex Earnshaw Date: Wed, 9 Oct 2019 13:46:01 +0100 Subject: [PATCH 4/4] remove javascript code for testing and set algolia to false --- layouts/partials/hooks/body-end.html | 9 +-------- layouts/partials/hooks/head-end.html | 1 - userguide/config.toml | 6 +++--- 3 files changed, 4 insertions(+), 12 deletions(-) diff --git a/layouts/partials/hooks/body-end.html b/layouts/partials/hooks/body-end.html index cff622b9f4..3e09f7aa17 100644 --- a/layouts/partials/hooks/body-end.html +++ b/layouts/partials/hooks/body-end.html @@ -1,10 +1,3 @@ {{ with .Site.Params.algolia_docsearch }} - - + {{ end }} \ No newline at end of file diff --git a/layouts/partials/hooks/head-end.html b/layouts/partials/hooks/head-end.html index 8dad9b8220..e25d67d4bc 100644 --- a/layouts/partials/hooks/head-end.html +++ b/layouts/partials/hooks/head-end.html @@ -1,4 +1,3 @@ {{ with .Site.Params.algolia_docsearch }} - {{ end }} \ No newline at end of file diff --git a/userguide/config.toml b/userguide/config.toml index d2f7ec3af5..bea899235c 100644 --- a/userguide/config.toml +++ b/userguide/config.toml @@ -97,10 +97,10 @@ time_format_default = "January 2, 2006" rss_sections = ["blog"] # Google Custom Search Engine ID. Remove or comment out to disable search. -#gcs_engine_id = "011217106833237091527:la2vtv2emlw" +gcs_engine_id = "011217106833237091527:la2vtv2emlw" # Enable Algolia DocSearch -algolia_docsearch = true +algolia_docsearch = false # User interface configuration [params.ui] @@ -109,7 +109,7 @@ sidebar_menu_compact = false # Set to true to disable breadcrumb navigation. breadcrumb_disable = false # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) -sidebar_search_disable = true +sidebar_search_disable = false # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar navbar_logo = true