From e6c27b83fde49a954ccfeaf48041b6e4437d3f5e Mon Sep 17 00:00:00 2001
From: Mark Holmes <contact@markholm.es>
Date: Wed, 4 Jun 2025 00:02:41 -0500
Subject: [PATCH] docs: detail portfolio json

---
 README.md              | 53 ++++++++++++++++++++++++++++++++++++++++++
 portfolio.minimal.json |  7 ++++++
 2 files changed, 60 insertions(+)
 create mode 100644 portfolio.minimal.json

diff --git a/README.md b/README.md
index 8953926..aaa9548 100644
--- a/README.md
+++ b/README.md
@@ -48,3 +48,56 @@ defaults to the value in `DEFAULT_GOOGLE_FONTS_URL` inside `pages/index.js`.
 2. Add each font to your selection then open the **Get embed code** panel.
 3. Copy the `href` attribute from the `<link>` tag and place it in
    `style.fonts.googleFontsUrl`.
+
+## `portfolio.json` Reference
+
+The file `portfolio.json` controls what content appears on your portfolio site. Below is an explanation of every supported field and where to obtain its value.
+
+### Basic Fields
+
+* `title` – The main heading displayed on the page.
+* `pageTitle` – (optional) Title shown in the browser tab. Defaults to `title` when omitted.
+* `description` – Markdown text shown below the heading.
+* `googleAnalyticsID` – (optional) Measurement ID for Google Analytics. Create a property at [analytics.google.com](https://analytics.google.com), open the Web stream for your site and copy the *Measurement ID* (for example `G-XXXXXXX`).
+* `gravatarEmail` – (optional) Email address associated with your [Gravatar](https://gravatar.com) account. The site hashes this email to fetch the avatar image.
+
+### Favicon and Header Picture
+
+* `favicon.linkUrl` – URL to an image used as the browser favicon.
+* `favicon.useGravatar` – Set to `true` to use the avatar from `gravatarEmail` instead of `linkUrl`.
+* `headerPicture.linkUrl` – URL of the picture displayed in the page header.
+* `headerPicture.useGravatar` – Set to `true` to display your Gravatar.
+* `headerPicture.pictureText` – Alternate text for the header picture.
+
+### Styling
+
+The optional `style.colors` and `style.fonts` objects override the default colours and fonts as shown above. The `googleFontsUrl` value should be copied from the `href` attribute of the embed link on [Google Fonts](https://fonts.google.com).
+
+### Portfolio Links
+
+`portfolio` contains entries for the icons displayed on the page. Each entry accepts an optional `order` property to control its position. Supported entries are:
+
+* `github.username` – GitHub user name.
+* `twitter.handle` – Twitter handle without the `@`.
+* `bluesky.handle` – Bluesky handle.
+* `linkedIn.username` – LinkedIn profile name.
+* `email.address` – Email address for the mail link.
+* `bitbucket.username` – Bitbucket user name.
+* `stackOverflow.id` – Numeric user ID from your Stack Overflow profile URL.
+* `stackExchange.id` – Numeric user ID from your Stack Exchange profile URL.
+
+### Minimal Example
+
+`portfolio.minimal.json` contains the smallest possible configuration:
+
+```json
+{
+  "title": "Developer Name",
+  "description": "A short description about me.",
+  "portfolio": {
+    "github": { "username": "github" }
+  }
+}
+```
+
+Copy this file to `portfolio.json` and update the values to get started quickly.
diff --git a/portfolio.minimal.json b/portfolio.minimal.json
new file mode 100644
index 0000000..6ebb0b1
--- /dev/null
+++ b/portfolio.minimal.json
@@ -0,0 +1,7 @@
+{
+  "title": "Developer Name",
+  "description": "A short description about me.",
+  "portfolio": {
+    "github": { "username": "github" }
+  }
+}