diff --git a/docs/src/test-annotations-js.md b/docs/src/test-annotations-js.md
index bbc9a4a5ec..eaa0ea9749 100644
--- a/docs/src/test-annotations-js.md
+++ b/docs/src/test-annotations-js.md
@@ -212,3 +212,25 @@ test('user profile', async ({ page }) => {
   // ...
 });
 ```
+
+## Custom annotations
+
+It's also possible to add custom metadata in the form of annotations to your tests. Annotations are key/value pairs accessible via [`test.info().annotations`](./api/class-testinfo#test-info-annotations). Many reporters show annotations, for example `'html'`.
+
+```js js-flavor=js
+// example.spec.js
+
+test('user profile', async ({ page }) => {
+  test.info().annotations.push({ type: 'issue', description: 'https://github.com/microsoft/playwright/issues/<some-issue>' });
+  // ...
+});
+```
+
+```js js-flavor=ts
+// example.spec.ts
+
+test('user profile', async ({ page }) => {
+  test.info().annotations.push({ type: 'issue', description: 'https://github.com/microsoft/playwright/issues/<some-issue>' });
+  // ...
+});
+```