From 93dbdcce3836e2012b1a3d75c1bdfb82a5cf0150 Mon Sep 17 00:00:00 2001 From: LisaFC Date: Sat, 30 Apr 2022 19:04:44 +0100 Subject: [PATCH 1/3] Fix search input for latest version of Algolia (#985) * Fix search input for latest version of Algolia Fixes #845 * Document how to configure * Add note about migration * Implementing chalin's edits * Update CHANGELOG.md * CHANGELOG: mark 0.3.0 as unpublished, and other tweaks Co-authored-by: Patrice Chalin --- CHANGELOG.md | 19 ++++++++--- layouts/partials/search-input.html | 4 ++- .../en/docs/Adding content/navigation.md | 33 ++++++++++++++++--- 3 files changed, 46 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bee3e0e7b..141691b74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,19 +2,29 @@ Useful links: Docsy [releases][] & [tags][]. Jump to the [latest][] release. -## 0.X.Y - next release - For a list of issues targeted for the next release, see the [22Q2][] milestone. +## [0.3.0][] - next release (unpublished yet) + +**Breaking changes**: + +- Upgrade to [Algolia DocSearch v3](https://docsearch.algolia.com/docs/DocSearch-v3). + If your site uses the deprecated DocSearch v2, you must + [update your DocSearch code](https://docsearch.algolia.com/docs/migrating-from-v2). + +**Details**: + +- See the [release notes][0.3.0] + ## [0.2.0][] **New**: -- Official Docsy support for [Hugo modules][]. Many thanks to the dedicated and +- Add official Docsy support for [Hugo modules][]. Many thanks to the dedicated and patient efforts of [@deining][], who researched, experimented, and implemented this feature. Thanks to [@deining][] and [@LisaFC][] for the doc updates. -**Changes**: +**Details**: - See the [release notes][0.2.0] @@ -22,6 +32,7 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone. [@deining]: https://github.com/deining [@LisaFC]: https://github.com/LisaFC [0.2.0]: https://github.com/google/docsy/releases/v0.2.0 +[0.3.0]: https://github.com/google/docsy/releases/v0.3.0 [22Q2]: https://github.com/google/docsy/milestone/3 [Hugo modules]: https://gohugo.io/hugo-modules/ [latest]: https://github.com/google/docsy/releases/latest diff --git a/layouts/partials/search-input.html b/layouts/partials/search-input.html index c4956cc91..22e900247 100644 --- a/layouts/partials/search-input.html +++ b/layouts/partials/search-input.html @@ -1,5 +1,7 @@ -{{ if or .Site.Params.gcs_engine_id .Site.Params.algolia_docsearch -}} +{{ if .Site.Params.gcs_engine_id -}} +{{ else if .Site.Params.algolia_docsearch -}} +
{{ else if .Site.Params.offlineSearch -}} {{ $offlineSearchIndex := resources.Get "json/offline-search-index.json" | resources.ExecuteAsTemplate "offline-search-index.json" . -}} {{ if hugo.IsProduction -}} diff --git a/userguide/content/en/docs/Adding content/navigation.md b/userguide/content/en/docs/Adding content/navigation.md index 8761e689d..8edf154e0 100644 --- a/userguide/content/en/docs/Adding content/navigation.md +++ b/userguide/content/en/docs/Adding content/navigation.md @@ -189,13 +189,17 @@ If you don't specify a Google Custom Search Engine ID for your project and haven ## Configure Algolia DocSearch -As an alternative to GCSE, you can use [Algolia DocSearch](https://docsearch.algolia.com/) with this theme. Algolia DocSearch is free for public documentation sites. +As an alternative to GCSE, you can use [Algolia DocSearch](https://docsearch.algolia.com/) with this theme. Algolia DocSearch is free for public documentation sites. Docsy supports Algolia DocSearch v3. + +{{% alert title="Note" %}} +Docsy previously supported Algolia DocSearch v2, which is now deprecated. If you are an existing Algolia DocSearch v2 user and want to use the latest Docsy version, [follow the migration instructions](https://docsearch.algolia.com/docs/migrating-from-v2) in the DocSearch documentation to update your DocSearch code snippet. +{{% /alert %}} ### Sign up for Algolia DocSearch Complete the form at [https://docsearch.algolia.com/apply/](https://docsearch.algolia.com/apply/). -If you are accepted to the program, you will receive the JavaScript code to add to your documentation site from Algolia by email. +If you are accepted to the program, you will receive the code to add to your documentation site from Algolia by email. ### Adding Algolia DocSearch @@ -210,11 +214,30 @@ If you are accepted to the program, you will receive the JavaScript code to add 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. +3. Add the CSS and JS to use Algolia to the head and body of every page in your site, following the instructions in [Add code to head or before body end](/docs/adding-content/lookandfeel/#add-code-to-head-or-before-body-end). + + * In `head-end.html` add the DocSearch CSS: + + ```html + + ``` + + + * In `body-end.html` add the DocSearch script, replacing the `docsearch` details with the snippet you get from Algolia (the example below is Algolia's own site index!). You must provide `#docsearch` as your `container` value as that's the ID of the `div` we provide in Docsy's layout: + + ```html + + + ``` -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). +You can find out more about how to configure DocSearch in the Algolia DocSearch V3 [Getting started](https://docsearch.algolia.com/docs/DocSearch-v3) guide. -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. +When you've completed these steps, 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. ## Configure local search with Lunr From 6fc622c3874b2af8d1d72a9212bf64acb41d9823 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 30 Apr 2022 14:13:41 -0400 Subject: [PATCH 2/3] Update CHANGELOG.md (#997) --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 141691b74..b01d8e42b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone. - Add official Docsy support for [Hugo modules][]. Many thanks to the dedicated and patient efforts of [@deining][], who researched, experimented, and implemented this feature. Thanks to [@deining][] and [@LisaFC][] for the doc updates. + + For details, see [Migrate to Hugo Modules](https://www.docsy.dev/docs/updating/convert-site-to-module/). **Details**: From f4d2ff87b17dfeb4c0282c49d35451d1ae362028 Mon Sep 17 00:00:00 2001 From: Geri Ochoa Date: Mon, 9 May 2022 13:06:10 -0400 Subject: [PATCH 3/3] Update readfile shortcode (#995) This shortcode allows inserting the content of a file into another to reuse content. Changes: - Support for relative paths - Support for a single positional parameter - Documentation added --- layouts/shortcodes/readfile.html | 36 ++++++ layouts/shortcodes/readfile.md | 8 -- .../Shortcodes/includes/config.yaml | 11 ++ .../Shortcodes/includes/installation.md | 10 ++ .../docs/Adding content/Shortcodes/index.md | 104 ++++++++++++++++++ 5 files changed, 161 insertions(+), 8 deletions(-) create mode 100644 layouts/shortcodes/readfile.html delete mode 100644 layouts/shortcodes/readfile.md create mode 100644 userguide/content/en/docs/Adding content/Shortcodes/includes/config.yaml create mode 100644 userguide/content/en/docs/Adding content/Shortcodes/includes/installation.md diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html new file mode 100644 index 000000000..f858502a4 --- /dev/null +++ b/layouts/shortcodes/readfile.html @@ -0,0 +1,36 @@ +{{/* Handle the "file" named parameter or a single unnamed parameter as the file +path */}} +{{ if .IsNamedParams }} + {{ $.Scratch.Set "fparameter" ( .Get "file" ) }} +{{ else }} + {{ $.Scratch.Set "fparameter" ( .Get 0 ) }} +{{ end }} + + +{{/* If the first character is "/", the path is absolute from the site's +`baseURL`. Otherwise, construct an absolute path using the current directory */}} + +{{ if eq (.Scratch.Get "fparameter" | printf "%.1s") "/" }} + {{ $.Scratch.Set "filepath" ($.Scratch.Get "fparameter") }} +{{ else }} + {{ $.Scratch.Set "filepath" "/" }} + {{ $.Scratch.Add "filepath" $.Page.File.Dir }} + {{ $.Scratch.Add "filepath" ($.Scratch.Get "fparameter") }} +{{ end }} + + +{{/* If the file exists, read it and highlight it if it's code. Throw an error +if the file is not found */}} + +{{ if fileExists ($.Scratch.Get "filepath") }} + {{ if eq (.Get "code") "true" }} + {{- highlight ($.Scratch.Get "filepath" | readFile | htmlUnescape | + safeHTML ) (.Get "lang") "" -}} + {{ else }} + {{- $.Scratch.Get "filepath" | readFile | htmlUnescape | safeHTML -}} + {{ end }} +{{ else }} + +

The file {{ $.Scratch.Get "filepath" }} was not found.

+ +{{ end }} diff --git a/layouts/shortcodes/readfile.md b/layouts/shortcodes/readfile.md deleted file mode 100644 index 117c7e870..000000000 --- a/layouts/shortcodes/readfile.md +++ /dev/null @@ -1,8 +0,0 @@ -{{$file := .Get "file"}} -{{- if eq (.Get "markdown") "true" -}} -{{- $file | readFile | markdownify -}} -{{- else if (.Get "highlight") -}} -{{- highlight ($file | readFile) (.Get "highlight") "" -}} -{{- else -}} -{{ $file | readFile | safeHTML }} -{{- end -}} diff --git a/userguide/content/en/docs/Adding content/Shortcodes/includes/config.yaml b/userguide/content/en/docs/Adding content/Shortcodes/includes/config.yaml new file mode 100644 index 000000000..e28cac21b --- /dev/null +++ b/userguide/content/en/docs/Adding content/Shortcodes/includes/config.yaml @@ -0,0 +1,11 @@ +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: hello +spec: + steps: + - name: echo + image: alpine + script: | + #!/bin/sh + echo "Hello World" diff --git a/userguide/content/en/docs/Adding content/Shortcodes/includes/installation.md b/userguide/content/en/docs/Adding content/Shortcodes/includes/installation.md new file mode 100644 index 000000000..da1c7edd6 --- /dev/null +++ b/userguide/content/en/docs/Adding content/Shortcodes/includes/installation.md @@ -0,0 +1,10 @@ +**Installation** + +1. Download the installation files. + +1. Run the installation script + + `sudo sh install.sh` + +1. Test that your installation was successfully completed. + diff --git a/userguide/content/en/docs/Adding content/Shortcodes/index.md b/userguide/content/en/docs/Adding content/Shortcodes/index.md index 3526aa5d7..735e2a88f 100644 --- a/userguide/content/en/docs/Adding content/Shortcodes/index.md +++ b/userguide/content/en/docs/Adding content/Shortcodes/index.md @@ -497,3 +497,107 @@ File[] hiddenFiles = new File("directory_name") {{< /card-code >}} {{< /cardpane >}} +## Include external files + +Sometimes there's content that is relevant for several documents, or that is +maintained in a file that is not necessarily a document. For situations like +these, the `readfile` shortcode allows you to import the contents of an external +file into a document. + +### Reuse documentation + +In case you want to reuse some content in several documents, you can write said +content in a separate file and include it wherever you need it. + +For example, suppose you have a file called `installation.md` with the following +contents: + +```go-html-template +## Installation + +1. Download the installation files. + +1. Run the installation script + + `sudo sh install.sh` + +1. Test that your installation was successfully completed. + +``` + +You can import this section into another document: + +```go-html-template +The following section explains how to install the database: + +{{%/* readfile "installation.md" */%}} + +``` + +This will be rendered as if the instructions were in the parent document: + +--- + +The following section explains how to install the database: + +{{% readfile "includes/installation.md" %}} + +--- + +The parameter is the relative path to the file. Only relative paths +under the parent file's working directory are supported. + +For files outside the current working directory you can use an absolute path +starting with `/`. The root directory is the `/content` folder. + +### Include code files + +Suppose you have an `includes` folder containing several code samples you want +to use as part of your documentation. You can use `readfile` with some +additional parameters: + +```go-html-template +To create a new pipeline, follow the next steps: + +1. Create a configuration file `config.yaml`: + + {{}} + +1. Apply the file to your cluster `kubectl apply config.yaml` + +``` + +This code automatically reads the content of `import/config.yaml` and inserts it +into the document. The rendered text looks like this: + +--- + +To create a new pipeline, follow the next steps: + +1. Create a configuration file `config.yaml`: + + {{< readfile file="includes/config.yaml" code="true" lang="yaml" >}} + +1. Apply the file to your cluster `kubectl apply config.yaml` + +--- + +{{% alert title="Warning" color="warning" %}} +You must use `{{}}` delimiters for the code highlighting to work +correctly. +{{% /alert %}} + +The "file" parameter is the relative path to the file. Only relative paths +under the parent file's working directory are supported. + +For files outside the current working directory you can use an absolute path +starting with `/`. The root directory is the `/content` folder. + + + +| Parameter | Default | Description | +| ---------------- |------------| ------------| +| file | | Path of external file| +| code | false | Boolean value. If `true` the contents is treated as code| +| lang | plain text | Programming language | +