From e6e5ae2a914d5687b629f91d276480d7974c4f49 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 12 Jun 2024 18:55:48 +0200
Subject: [PATCH] docs: intial package metadata docs

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 docs/tooling/package-metadata.md | 13 +++++++++++++
 microsite/sidebars.json          |  3 ++-
 mkdocs.yml                       |  1 +
 3 files changed, 16 insertions(+), 1 deletion(-)
 create mode 100644 docs/tooling/package-metadata.md

diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md
new file mode 100644
index 0000000000..cbd0799ad3
--- /dev/null
+++ b/docs/tooling/package-metadata.md
@@ -0,0 +1,13 @@
+---
+id: package-metadata
+title: Package Metadata
+description: An inventory of well known package metadata fields in the Backstage ecosystem.
+---
+
+The `package.json` file is a JSON file that contains metadata about a JavaScript package, and in required for all package publish to NPM or a similar package registry. It is a [Node.js standard](https://nodejs.org/api/packages.html) that is expanded upon in the [NPM ecosystem](https://docs.npmjs.com/cli/v10/configuring-npm/package-json).
+
+## Known Metadata Fields
+
+This section documents the known `package.json` metadata fields that play a significant role in the Backstage ecosystem.
+
+All [fields defined by NPM](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) are inherited by the Backstage ecosystem. The list below only includes those standard fields for which additional information is available.
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index 5ddd2f97f1..3ba9feeecd 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -362,7 +362,8 @@
           "tooling/local-dev/linking-local-packages",
           "tooling/local-dev/debugging"
         ]
-      }
+      },
+      "tooling/package-metadata"
     ],
     "Deployment": [
       "deployment/index",
diff --git a/mkdocs.yml b/mkdocs.yml
index 026e76d531..110aa0933a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -180,6 +180,7 @@ nav:
       - Local Development:
           - Linking in Local Packages: 'tooling/local-dev/linking-local-packages.md'
           - Debugging Backstage: 'tooling/local-dev/debugging.md'
+      - Package Metadata: 'tooling/package-metadata.md'
   - Deployment:
       - Deploying Backstage: 'deployment/index.md'
       - Scaling: 'deployment/scaling.md'