Publishing Adapters and Templates to istio.io

If you've written a great new Mixer adapter and you'd like to make it available to as many Istio users as possible, you should consider listing your adapter on istio.io. It's easy.

1. Document your adapter or template. To create adapters and templates, you need to author proto files. Please fully document the proto messages and individual fields, with an eye towards an operator that is trying to use your component. Example YAML is highly desirable in this documentation. You can see many examples of properly documented adapters in the core Mixer adapters.

2. Annotate your adapter or template. To get your documentation on istio.io, it needs to have a few special annotations. Those are introduced via a stand-alone comment at the top of your proto file. These special comments are of the form:

   // $keyword: value

   These comments are used by Istio's documentation machinery to integrate your documentation into the overall website. The set of keywords that you can use are:

   Keyword	Required	Description
   title	Yes	The short name of your component.
   description	Yes	A one sentence description of your component.
   location	Yes	The URL within istio.io where your component's documentation should go. This should be https://istio.io/docs/reference/config/policy-and-telemetry/adapters/*adapter name*.html for adapters and https://istio/docs/reference/config/policy-and-telemetry/templates/*template name*.html for templates.
   provider	No	The name of your company, or your name if you're an individual contributor.
   contact_email	No	A contact email address for customers trying to get in touch with you.
   support_link	No	A URL to a support website for the component.
   latest_release_link	No	A link to a release page showing the latest available release of your component.
   helm_chart_link	No	A link to a Helm chart allowing users to install your component.
   source_link	No	A link to the source code for your component.
   istio_versions	No	A comma-separated list of Istio versions that you have tested your component with. Enclose this list in double-quotes.
   supported_templates	No	For adapters, a comma-separated list of templates the adapter supports.
   logo_link	No	A link to a logo to display on the documentation page.

3. Build your component. Building your component should result in a .pb.html file which holds the documentation for your component. You need to commit that .pb.html file to a public Git repo so that the Istio documentation machinery can find it.

4. Register your adapter or template. Once you have checked in the .pb.html file to your public Git repo, you need to head over to istio/istio.io and create a PR that adds your repo's address to the REPOS variable in the scripts/grab_reference_docs.sh script. Once your PR is committed, the Istio documentation machinery will eventually run, discover your repo, then find your .pb.html file, and publish it to istio.io alongside all the other adapters.

Here's an example of what all these annotations end up looking like once the docs are published.