From 9b60bef5b65b610b86a9485321d2298730c2294f Mon Sep 17 00:00:00 2001
From: Andre Wanlin <awanlin@spotify.com>
Date: Mon, 16 Feb 2026 18:14:50 -0600
Subject: [PATCH] Docs

Signed-off-by: Andre Wanlin <awanlin@spotify.com>
---
 docs/plugins/plugin-directory-audit.md | 23 +++++++++++++++++++++++
 microsite/sidebars.ts                  |  2 +-
 microsite/src/pages/plugins/index.tsx  |  2 +-
 3 files changed, 25 insertions(+), 2 deletions(-)
 create mode 100644 docs/plugins/plugin-directory-audit.md

diff --git a/docs/plugins/plugin-directory-audit.md b/docs/plugins/plugin-directory-audit.md
new file mode 100644
index 0000000000..69eb33da88
--- /dev/null
+++ b/docs/plugins/plugin-directory-audit.md
@@ -0,0 +1,23 @@
+---
+id: plugin-directory-audit
+title: Plugin Directory Audit
+description: Details about the process for auditing plugins in the directory
+---
+
+## Audit Process
+
+We have a simple process in place to audit the plugins in the Plugin Directory:
+
+1. On a quarterly basis we run the following script: `node ./scripts/plugin-directory-audit.js --audit`
+2. This script will flag any plugin that has not been updated on NPM in more than 365 days as `archived` if it was `inactive`.
+3. It will also flag any plugin as `inactive` that has not been updated on NPM in more than 365 days if it was `active`.
+4. For any plugin flagged as `inactive` or `archived` and have been updated on NPM in less than 365 days they will be flagged as `active` again.
+5. These changes will then be submitted as a PR, approved and merged.
+
+The impact of a plugin being set to `inactive` means they will show in the inactive section at the bottom of the Plugin Directory. A plugin that is set to `archived` will **not** show up in the Plugin Directory at all.
+
+:::tip
+
+If your plugin moved to `inactive` or `archived` and you update it, please submit a PR to update the status to `active`!
+
+:::
diff --git a/microsite/sidebars.ts b/microsite/sidebars.ts
index b3053e3953..f70de52324 100644
--- a/microsite/sidebars.ts
+++ b/microsite/sidebars.ts
@@ -438,7 +438,7 @@ export default {
         ),
         sidebarElementWithIndex(
           { label: 'Publishing', description: 'Publishing your plugins.' },
-          ['plugins/publish-private', 'plugins/add-to-directory'],
+          ['plugins/publish-private', 'plugins/add-to-directory', 'plugins/plugin-directory-audit'],
         ),
         'plugins/observability',
       ],
diff --git a/microsite/src/pages/plugins/index.tsx b/microsite/src/pages/plugins/index.tsx
index 0eb6f2849e..9c4ba04318 100644
--- a/microsite/src/pages/plugins/index.tsx
+++ b/microsite/src/pages/plugins/index.tsx
@@ -222,7 +222,7 @@ const Plugins = () => {
             <h2>Inactive Plugins ({inactivePlugins.length})</h2>
             <p>
               These plugins are no longer actively maintained as their NPM package has not seen an update in more than 365 days. They are kept here for reference but may not work with
-              current versions of Backstage.
+              current versions of Backstage. Details on the audit process can be found in the <Link to="/docs/plugins/plugin-directory-audit">Plugin Directory Audit</Link> documentation.
             </p>
             <div className="pluginsContainer margin-bottom--lg">
               {inactivePlugins.map(pluginData => (