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

5 files changed, 161 insertions, 8 deletions

diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html
new file mode 100644
index 0000000..f858502
--- /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 }}
+
+<p style="color: #D74848"><b><i>The file <code>{{ $.Scratch.Get "filepath" }}</code> was not found.</i></b></p>
+
+{{ end }}
diff --git a/layouts/shortcodes/readfile.md b/layouts/shortcodes/readfile.md
deleted file mode 100644
index 117c7e8..0000000
--- 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 0000000..e28cac2
--- /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 0000000..da1c7ed
--- /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 3526aa5..735e2a8 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`:
+
+    {{</* 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 |
+