site: custom index docs (#618)

* Add initial docs for multi index feature

* Add developer guide doc on custom indexes

* Add formatting around krew-index

* Small tweaks

* Add note about duplicate plugin names

* combine user guides, rephrase

Signed-off-by: Ahmet Alp Balkan <[email protected]>

* Fix small typo

* Extend the developer guide

Signed-off-by: Ahmet Alp Balkan <[email protected]>

* Fix typo

* Set as draft

* Update site/content/docs/user-guide/using-custom-indexes.md

Co-authored-by: Cornelius Weig <[email protected]>

* Update custom plugin install section of guide

* Add advanced usage section on removing default index

* Add section on the default index

* Code review changes

Co-authored-by: Ahmet Alp Balkan <[email protected]>
Co-authored-by: Cornelius Weig <[email protected]>

site/content/docs/developer-guide/custom-indexes.md

@@ -0,0 +1,44 @@
+---
+title: Hosting Custom Plugin Indexes
+slug: custom-indexes
+weight: 500
+draft: true
+---
+
+Krew comes with a plugin index named `default` that points to the
+[`krew-index` repository](https://github.com/kubernetes-sigs/krew) which allows
+centralized discovery through community curation.
+
+However, you can host your own plugin indexes (and possibly remove/replace the
+`default` index). It’s not recommended to host your own plugin index, unless you
+have a use case such as:
+
+- your plugin is not accepted to `krew-index`
+- you want full control over the distribution lifecycle of your own plugin
+- you want to run a _private_ plugin index in your organization (e.g. to be
+  installed on developer machines)
+
+Hosting your own custom index is simple:
+
+- Custom index repositories must be `git` repositories.
+- Your clients should have read access to the repository (if the repository
+  is not public, users can still authenticate to it with SSH keys or other
+  [gitremote-helpers](https://git-scm.com/docs/gitremote-helpers) installed
+  on the client machine).
+- The repository must contain a `plugins/` directory at the root, with at least
+  one plugin manifest in it. Plugin manifests should be directly in this
+  directory.
+- Ensure plugin manifests are valid YAML and passes Krew manifest validation
+  (optionally, you can use the
+  [validate-krew-manifest](https://github.com/kubernetes-sigs/krew/tree/master/cmd/validate-krew-manifest)
+  tool for static analysis).
+
+Example plugin repository layout:
+
+```text
+.
+└── plugins/
+    ├── plugin-a.yaml
+    ├── plugin-b.yaml
+    └── plugin-c.yaml
+```

site/content/docs/developer-guide/plugin-stats.md

@@ -1,7 +1,7 @@
 ---
 title: Plugin usage analytics
 slug: plugin-stats
-weight: 500
+weight: 600
 ---
 
 Krew does not track user behavior. However, for plugins that distribute their

site/content/docs/user-guide/using-custom-indexes.md

@@ -0,0 +1,97 @@
+---
+title: Using Custom Plugin Indexes
+slug: custom-indexes
+weight: 800
+draft: true
+---
+
+Plugin indexes contain plugin manifests, which are documents that describe
+installation procedure for a plugin. For discovery purposes, Krew comes with a
+`default` plugin index, plugins hosted in the [`krew-index` repository][ki].
+
+However, some plugin authors may choose to host their own indexes that contain
+their curation of kubectl plugins. These are called "custom plugin indexes".
+
+## Adding a custom index
+
+A custom plugin index can be added with the `kubectl krew index add` command:
+
+```sh
+{{<prompt>}}kubectl krew index add foo https://github.com/foo/custom-index.git
+```
+
+The URI you use can be any [git remote](https://git-scm.com/docs/git-remote)
+(e.g., `[email protected]:foo/custom-index.git`).
+
+## Removing a custom index
+
+You can remove a custom plugin index by passing the name it was added with to
+the remove command:
+
+```sh
+{{<prompt>}}kubectl krew index remove foo
+```
+
+## Listing indexes
+
+To see what indexes you have added run the list command:
+
+```sh
+{{<prompt>}}kubectl krew index list
+{{<output>}}INDEX    URL
+default  https://github.com/kubernetes-sigs/krew-index.git
+foo      https://github.com/foo/custom-index.git{{</output>}}
+```
+
+## Installing plugins from custom indexes
+
+Commands for managing plugins (e.g. `install`, `upgrade`) work with custom
+indexes as well.
+
+By default, Krew prefixes plugins with a `default/` prefix. So to install
+a plugin from a custom index, you need to specify it in the format
+`INDEX_NAME/PLUGIN_NAME`.
+
+For example, to install a plugin named `bar` from custom index `foo`:
+
+```sh
+{{<prompt>}}kubectl krew install foo/bar
+```
+
+Similarly:
+
+- To list all plugins (including the ones from custom indexes), run:
+
+    ```sh
+    {{<prompt>}}kubectl krew search
+    ```
+
+- To remove a plugin, you don't need to specify its index:
+
+    ```sh
+    {{<prompt>}}kubectl krew uninstall PLUGIN_NAME
+    ```
+
+- To get information about a plugin from a custom index:
+
+    ```sh
+    {{<prompt>}}kubectl krew info INDEX_NAME/PLUGIN_NAME
+    ```
+
+
+> **Caveat:** If two indexes offer a plugin with the same name, only one can
+> be installed at any time.
+
+## The default index
+
+When a plugin doesn't have an explicit `INDEX_NAME` prefix, it refers to a plugin
+from the `default` index. These plugins have an implicit `default/` prepended to
+them in Krew commands. The `INDEX_NAME` prefix is used to differentiate plugins
+with the same name across different indexes.
+
+Krew ships with [`krew-index`][ki] as the `default` index, but this can be
+removed using the `kubectl krew index remove default` command. Once this is
+removed, you can add another index with the name `default` and plugins from it
+will not require the `INDEX_NAME` prefix in commands.
+
+[ki]: https://github.com/kubernetes-sigs/krew-index