Merge branch 'main' into module_proxy

CHANGELOG.md

@@ -2,26 +2,39 @@
 
 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.
+
+  For details, see [Migrate to Hugo Modules](https://www.docsy.dev/docs/updating/convert-site-to-module/).
 
-**Changes**:
+**Details**:
 
 - See the [release notes][0.2.0]
 
 
 [@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

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 -}}
 <input type="search" class="form-control td-search-input" placeholder="&#xf002; {{ T "ui_search" }}" aria-label="{{ T "ui_search" }}" autocomplete="off">
+{{ else if .Site.Params.algolia_docsearch -}}
+<div id="docsearch"></div>
 {{ else if .Site.Params.offlineSearch -}}
 {{ $offlineSearchIndex := resources.Get "json/offline-search-index.json" | resources.ExecuteAsTemplate "offline-search-index.json" . -}}
 {{ if hugo.IsProduction -}}

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 }}
+
+<p style="color: #D74848"><b><i>The file <code>{{ $.Scratch.Get "filepath" }}</code> was not found.</i></b></p>
+
+{{ end }}

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"  

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.
+

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`:
+
+    {{</* readfile file="includes/config.yaml" code="true" lang="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 |
+

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
+      <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
+      ```
+   
+
+   * 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
+      <script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
+      <script type="text/javascript">docsearch({
+        container: '#docsearch',
+        appId: 'R2IYF7ETH7',
+        apiKey: '599cec31baffa4868cae4e79f180729b',
+        indexName: 'docsearch',
+        });</script>
+     ```
 
-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