Document how to embed artifacts on other websites (#3011)

Closes #2979

Signed-off-by: Sergio Castaño Arteaga <[email protected]>
Signed-off-by: Cintia Sanchez Garcia <[email protected]>
Co-authored-by: Sergio Castaño Arteaga <[email protected]>
Co-authored-by: Cintia Sanchez Garcia <[email protected]>

.github/dependabot.yml

@@ -43,7 +43,7 @@ updates:
       day: "wednesday"
     ignore:
       - dependency-name: "node"
-        versions: ["18-alpine3.16", "19-alpine3.16"]
+        versions: ["18-alpine3.16", "19-alpine3.16", "20-alpine3.16"]
   - package-ecosystem: "docker"
     directory: "/cmd/scanner"
     schedule:

.gitignore

@@ -5,6 +5,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+.hugo_build.lock
 node_modules/
 web/build
 web/public/docs

docs/embedding_artifacts.md

@@ -0,0 +1,52 @@
+# Embedding artifacts
+
+Artifact Hub allows embedding a single artifact or a group of them in other websites.
+
+## Embedding a single artifact
+
+You can embed an Artifact Hub package on other websites by adding the corresponding embed code. The embed code is a piece of HTML that can be generated from the Artifact Hub UI.
+
+Let's go through an example to see how this works.
+
+The first step is to find the package you'd like to embed on <https://artifacthub.io>. For this example, we'll use the [Artifact Hub Helm chart](https://artifacthub.io/packages/helm/artifact-hub/artifact-hub). On the top right corner of the package view you'll see a button with three dots.
+
+![Embed screenshot](https://artifacthub.github.io/hub/screenshots/embed-screenshot-1.jpg)
+
+If you click on it, you'll see an entry named `Embed widget`, which opens the widget configurator. From it you can customize the widget's appearance to suit your needs. Once you are done, you can copy the resulting embed code by clicking on `copy code to clipboard` at the bottom.
+
+![Embed screenshot](https://artifacthub.github.io/hub/screenshots/embed-screenshot-2.jpg)
+
+The generated code would be something like this:
+
+```html
+<div
+  class="artifacthub-widget"
+  data-url="https://artifacthub.io/packages/helm/artifact-hub/artifact-hub"
+  data-theme="light"
+  data-header="true"
+  data-stars="true"
+  data-responsive="false"
+>
+  <blockquote>
+     <p lang="en" dir="ltr"><b>artifact-hub</b>: Artifact Hub is a web-based application that enables finding, installing, and publishing Kubernetes packages.</p>
+     &mdash; Open in <a href="https://artifacthub.io/packages/helm/artifact-hub/artifact-hub">Artifact Hub</a>
+  </blockquote>
+</div>
+<script async src="https://artifacthub.io/artifacthub-widget.js"></script>
+```
+
+To verify it works as expected, you can give it a quick try on JSFiddle if you'd like: <https://jsfiddle.net/r0ox4c9a/>.
+
+## Embedding a group of artifacts
+
+Embedding a group of artifacts is very similar to embedding a single one. The main difference is that, instead of opening the widget configurator from the package view, it is opened from the search results view.
+
+![Embed screenshot](https://artifacthub.github.io/hub/screenshots/embed-screenshot-3.jpg)
+
+This allows you to use all the search filters available to select what packages you'd like to embed on the other website. You could choose all packages of a given kind, those published by a given organization or all packages provided by CNCF projects, for example. Then, from the configurator, you can customize the appearance of the widgets like we did on the previous case with a single artifact.
+
+![Embed screenshot](https://artifacthub.github.io/hub/screenshots/embed-screenshot-4.jpg)
+
+Once you are ready to go, you can copy the embed code and add it to the website you'd like to embed the artifacts on.
+
+You can see a widgets group in action in [this JSFiddle](https://jsfiddle.net/7nvkcfqb/).

docs/www/content/_index.md

@@ -19,7 +19,8 @@ The documentation is organized in the following topics:
 | [Kubewarden annotations](/docs/topics/annotations/kubewarden) | Describes some custom annotations that allow enriching the existing metadata in Kubewarden policies to improve users' experience in Artifact Hub.       |
 | [Kyverno annotations](/docs/topics/annotations/kyverno)       | Describes some custom annotations that allow enriching the existing metadata in Kyverno policies to improve users' experience in Artifact Hub.          |
 | [OLM annotations](/docs/topics/annotations/olm)               | Describes some custom annotations that allow enriching the existing metadata in OLM operators to improve users' experience in Artifact Hub.             |
-| [Tekton annotations](/docs/topics/annotations/tekton)         | Describes some custom annotations that allow enriching the existing metadata in Tekton tasks to improve users' experience in Artifact Hub.              |
+| [Tekton annotations](/docs/topics/annotations/tekton)         | Describes some custom annotations that allow enriching the existing metadata in Tekton tasks to improve users' experience in Artifact Hub.
+| [Embedding artifacts](/docs/topics/embedding_artifacts)       | Explains how to embed a single artifact or a group of them in other websites.              |
 | [Packages security report](/docs/topics/security_report)      | Explains how packages are scanned for security vulnerabilities and the structure of the security report.                                                |
 | [Authorization](/docs/topics/authorization)                   | Explains how the authorization mechanism that allows organizations to define what actions can be performed by their members works and how to set it up. |
 | [Architecture](/docs/topics/architecture)                     | Describes the components that form Artifact Hub, what each of them do and the layout of the source repository.                                          |

docs/www/headers/architecture

@@ -1,6 +1,6 @@
 ---
 title: "Architecture"
-weight: 5
+weight: 6
 aliases: [
   "/architecture",
 ]

docs/www/headers/authorization

@@ -1,6 +1,6 @@
 ---
 title: "Authorization"
-weight: 4
+weight: 5
 aliases: [
   "/authorization",
 ]

docs/www/headers/cli

@@ -1,6 +1,6 @@
 ---
 title: "CLI tool"
-weight: 8
+weight: 9
 aliases: [
   "/cli",
 ]

docs/www/headers/dev

@@ -1,6 +1,6 @@
 ---
 title: "Development environment setup"
-weight: 6
+weight: 7
 aliases: [
   "/dev",
 ]

docs/www/headers/embedding_artifacts

@@ -0,0 +1,7 @@
+---
+title: "Embedding artifacts"
+weight: 3
+aliases: [
+  "/embedding_artifacts",
+]
+---

docs/www/headers/infrastructure

@@ -1,6 +1,6 @@
 ---
 title: "Infrastructure"
-weight: 7
+weight: 8
 aliases: [
   "/infrastructure",
 ]

docs/www/headers/security_report

@@ -1,6 +1,6 @@
 ---
 title: "Packages security report"
-weight: 3
+weight: 4
 aliases: [
   "/security_report",
 ]

scripts/prepare-docs.sh

@@ -36,3 +36,4 @@ cat docs/www/headers/kubewarden_annotations docs/kubewarden_annotations.md > doc
 cat docs/www/headers/kyverno_annotations docs/kyverno_annotations.md > docs/www/content/topics/annotations/kyverno.md
 cat docs/www/headers/olm_annotations docs/olm_annotations.md > docs/www/content/topics/annotations/olm.md
 cat docs/www/headers/tekton_annotations docs/tekton_annotations.md > docs/www/content/topics/annotations/tekton.md
+cat docs/www/headers/embedding_artifacts docs/embedding_artifacts.md > docs/www/content/topics/embedding_artifacts.md