docusaurus-plugin-myog 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyOG.social
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# docusaurus-plugin-myog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Adds an `og:image` and `twitter:image` to each page of a Docusaurus site. It
+covers docs, versioned docs, blog posts, blog lists, tag pages and custom pages.
+[MyOG.social](https://myog.social) generates each image from the page's URL,
+using its content and branding automatically.
+
+The plugin writes metadata. It does not fetch images or call MyOG during builds
+or navigation. Social platforms request the image URL when they preview a page.
+
+Maintained by [MyOG.social](https://myog.social). The plugin is MIT licensed;
+the image service requires a paid plan or card trial.
+
+## Requirements and tested support
+
+- Docusaurus **3.10 or a later 3.x release**: stable `@docusaurus/core`
+  `>=3.10.0 <4.0.0`. Tested with 3.10.0 and 3.10.2. The runtime check rejects
+  older releases, prereleases and Docusaurus 4, which is not supported yet.
+- Docusaurus 3.10.0 itself fails plain webpack builds with webpack 5.106 or
+  newer, before any plugin runs (its webpackbar 6 dependency). 3.10.1 fixed
+  this. Use 3.10.1 or later, or Rspack.
+- Tested with the classic preset, React/react-dom **19.3.1** and **18.3.1**,
+  Node.js **24.1.0** and **20.11.0**, plain **webpack** and **Rspack** builds.
+  Rspack uses `@docusaurus/faster` at the core version with `future.v4: true`;
+  the webpack fixture explicitly disables `future.v4` and `future.faster`.
+  These are representative combinations, not every combination of those values.
+- Node.js 20.11.0 or newer is required. Later Node releases are not all tested.
+- A MyOG account with the site's domain registered and an active subscription
+  or trial. Image generation and refreshes use the plan's credits. The plugin
+  does not register domains, start trials or bypass usage limits.
+- Your account ID, copied from the `a=` value in the install code on
+  [the Docusaurus guide](https://myog.social/docs/docusaurus). It appears in each
+  image URL and is not a secret.
+
+The integration uses the documented `configureWebpack` hook, but remapping the
+resolved theme alias and relying on core App's metadata render order are
+**undocumented internal contracts**. The build fails if the required alias is
+missing, unsafe to wrap, or the core version is unsupported. See
+[DEVELOPMENT.md](https://github.com/MyOG-social/docusaurus-plugin-myog/blob/main/DEVELOPMENT.md)
+for the verification recipe.
+
+## Install
+
+In your Docusaurus 3.10+ site:
+
+```sh
+pnpm add docusaurus-plugin-myog@^0.2.0
+```
+
+Add the plugin to `docusaurus.config.ts` (or `.js`):
+
+```ts
+export default {
+  url: "https://docs.example.com",
+  // ...
+  plugins: [["docusaurus-plugin-myog", { account: "<account ID>" }]],
+}
+```
+
+Keep `themeConfig.image` and `themeConfig.metadata` if you use them. MyOG replaces
+their global `og:image` and `twitter:image` values; their other metadata stays.
+Remove static `og:image` and `twitter:image` entries from `headTags`, because
+Helmet cannot deduplicate them. The plugin warns about that conflict.
+
+Run `pnpm run build`, then inspect the generated HTML's `<head>`. Each image
+should appear once. On pages without an override, the MyOG URL's `url` parameter
+should decode to that page's `og:url`.
+
+## Options
+
+| Option     | Required | Default            | Description                                                                                   |
+| ---------- | -------- | ------------------ | --------------------------------------------------------------------------------------------- |
+| `account`  | yes      |                    | Your MyOG account ID (letters and digits).                                                    |
+| `template` | no       | `screenshot-right` | `brand`, `screenshot`, `screenshot-right`, `screenshot-bottom` or `screenshot-bottom-framed`. |
+
+The template selects the image composition. Automatic URL generation remains
+the product workflow; there is no per-page template setup.
+
+## Metadata priority and custom components
+
+From lowest to highest priority:
+
+1. Site defaults, including `themeConfig.image` and `themeConfig.metadata`.
+2. The MyOG image for the current page.
+3. A page's front matter `image` or MDX `<head>` image tags.
+
+An MDX block that sets only `og:image` keeps MyOG's `twitter:image`. Set both
+when both should use the override. A front matter image can equal the old
+global image and still wins.
+
+The plugin does not provide `@theme/Root`. Existing replacing or wrapping site
+Roots and Roots from other plugins retain their normal Docusaurus behavior.
+No Root wrapping or plugin ordering change is required for MyOG.
+
+A site-ejected `SiteMetadata` is preserved: MyOG wraps the component already
+resolved by Docusaurus and passes its props through. A theme's component or
+core's empty fallback is handled the same way. The plugin does not substitute
+`@theme-init/SiteMetadata`, which could discard theme or site metadata. A custom
+component must retain any first-party metadata the site needs. Competing plugins
+that remap this same alias are outside tested support.
+
+## Limits
+
+- `url`, `baseUrl` and `trailingSlash` must match the deployed site. The image
+  URL uses `siteConfig.url` plus the current route path, matching Docusaurus's
+  `og:url` in generated HTML.
+- During client navigation, non-ASCII paths use the browser's percent-encoded
+  pathname. Generated HTML retains Docusaurus's canonical URL representation.
+- Each distinct page URL gets its own image; `/a` and `/a/` count separately.
+  Generation and periodic refreshes use credits from the monthly allowance
+  ([pricing](https://myog.social/pricing)). A large site can exhaust it.
+- One plugin instance per site. Static `headTags` image tags must be removed.
+- Verified with `docusaurus build`, `serve` hydration/client navigation and a
+  `docusaurus start` smoke test. Only the `en` locale was tested. i18n locale
+  paths and other themes are not verified. The experimental hash router is
+  unsupported because it produces one HTML page.
+- Social platforms cache images; use their debugger to refresh a card.
+
+## Uninstall
+
+Remove the plugin entry and run `pnpm remove docusaurus-plugin-myog`.
+Docusaurus uses the existing theme image settings again.
+
+## License
+
+MIT

package/lib/client/imageURL.js

@@ -0,0 +1,7 @@
+export const MYOG_IMAGE_ENDPOINT = "https://api.myog.social/og";
+// Matches the install snippet on https://myog.social/docs/docusaurus: the page URL is the
+// deployed site URL plus the route path, the same value Docusaurus emits as og:url.
+export function buildImageURL({ account, template, siteURL, pathname, }) {
+    const pageURL = siteURL + pathname;
+    return `${MYOG_IMAGE_ENDPOINT}?a=${encodeURIComponent(account)}&url=${encodeURIComponent(pageURL)}&template=${encodeURIComponent(template)}&src=docs`;
+}

package/lib/components/SiteMetadata.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import Head from "@docusaurus/Head";
+import { useLocation } from "@docusaurus/router";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import { usePluginData } from "@docusaurus/useGlobalData";
+import OriginalSiteMetadata from "@myog-original/SiteMetadata";
+import { buildImageURL } from "../client/imageURL.js";
+export default function SiteMetadata(props) {
+    const { siteConfig } = useDocusaurusContext();
+    const { pathname } = useLocation();
+    const { account, template } = usePluginData("docusaurus-plugin-myog");
+    const imageURL = buildImageURL({ account, template, siteURL: siteConfig.url, pathname });
+    return (_jsxs(_Fragment, { children: [_jsx(OriginalSiteMetadata, { ...props }), _jsxs(Head, { children: [_jsx("meta", { property: "og:image", content: imageURL }), _jsx("meta", { name: "twitter:image", content: imageURL })] })] }));
+}

package/lib/conflicts.d.ts

@@ -0,0 +1,3 @@
+export declare function findConflicts({ headTags }: {
+    headTags?: unknown;
+}): string[];

package/lib/conflicts.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findConflicts = findConflicts;
+const IMAGE_META_KEYS = new Set(["og:image", "twitter:image"]);
+function findConflicts({ headTags }) {
+    const staticTags = Array.isArray(headTags) ? headTags : [];
+    return staticTags.some((tag) => IMAGE_META_KEYS.has(String(tag?.attributes?.property)) ||
+        IMAGE_META_KEYS.has(String(tag?.attributes?.name)))
+        ? [
+            "headTags contains og:image or twitter:image outside Helmet, which puts a second image tag on every page. Remove those entries.",
+        ]
+        : [];
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+import type { LoadContext, Plugin } from "@docusaurus/types";
+import { type PluginOptions } from "./options";
+export type { PluginOptions, Template } from "./options";
+export default function pluginMyOG(context: LoadContext, options: PluginOptions): Plugin<void>;

package/lib/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = pluginMyOG;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const conflicts_1 = require("./conflicts");
+const siteMetadata_1 = require("./siteMetadata");
+const options_1 = require("./options");
+function pluginMyOG(context, options) {
+    const coreManifest = require.resolve("@docusaurus/core/package.json", {
+        paths: [context.siteDir],
+    });
+    const { version } = JSON.parse((0, node_fs_1.readFileSync)(coreManifest, "utf8"));
+    (0, siteMetadata_1.assertSupportedVersion)(version);
+    const data = (0, options_1.normalizeOptions)(options);
+    for (const conflict of (0, conflicts_1.findConflicts)({
+        headTags: context.siteConfig.headTags,
+    })) {
+        console.warn(`[${options_1.PLUGIN_NAME}] ${conflict}`);
+    }
+    return {
+        name: options_1.PLUGIN_NAME,
+        contentLoaded({ actions }) {
+            actions.setGlobalData(data);
+        },
+        configureWebpack(config) {
+            return (0, siteMetadata_1.wrapSiteMetadata)({
+                aliases: config.resolve?.alias,
+                wrapper: node_path_1.default.join(__dirname, "components/SiteMetadata.js"),
+            });
+        },
+    };
+}

package/lib/options.d.ts

@@ -0,0 +1,15 @@
+export declare const PLUGIN_NAME = "docusaurus-plugin-myog";
+export declare const TEMPLATES: readonly ["brand", "screenshot", "screenshot-right", "screenshot-bottom", "screenshot-bottom-framed"];
+export type Template = (typeof TEMPLATES)[number];
+export declare const DEFAULT_TEMPLATE: Template;
+export type PluginOptions = {
+    /** Your MyOG account ID, the `a=` value in the install snippet on https://myog.social/docs/docusaurus. */
+    account: string;
+    /** Image layout. Defaults to `screenshot-right`. */
+    template?: Template;
+};
+export type MyOGGlobalData = {
+    account: string;
+    template: Template;
+};
+export declare function normalizeOptions(raw: unknown): MyOGGlobalData;

package/lib/options.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.PLUGIN_NAME = void 0;
+exports.normalizeOptions = normalizeOptions;
+exports.PLUGIN_NAME = "docusaurus-plugin-myog";
+exports.TEMPLATES = [
+    "brand",
+    "screenshot",
+    "screenshot-right",
+    "screenshot-bottom",
+    "screenshot-bottom-framed",
+];
+exports.DEFAULT_TEMPLATE = "screenshot-right";
+function fail(message) {
+    throw new Error(`[${exports.PLUGIN_NAME}] ${message}`);
+}
+function normalizeOptions(raw) {
+    const options = (raw ?? {});
+    const { id, account, template, ...unknown } = options;
+    if (id !== undefined && id !== "default") {
+        fail("supports a single instance; remove the `id` option.");
+    }
+    const unknownKeys = Object.keys(unknown);
+    if (unknownKeys.length > 0) {
+        fail(`unknown option(s): ${unknownKeys.join(", ")}. Supported: account, template.`);
+    }
+    const trimmedAccount = typeof account === "string" ? account.trim() : "";
+    if (!/^[A-Za-z0-9]{1,32}$/.test(trimmedAccount)) {
+        fail("`account` must be your MyOG account ID (letters and digits), copied from the install snippet at https://myog.social/docs/docusaurus.");
+    }
+    const chosenTemplate = template ?? exports.DEFAULT_TEMPLATE;
+    if (!exports.TEMPLATES.includes(chosenTemplate)) {
+        fail(`\`template\` must be one of: ${exports.TEMPLATES.join(", ")}.`);
+    }
+    return { account: trimmedAccount, template: chosenTemplate };
+}

package/lib/siteMetadata.d.ts

@@ -0,0 +1,13 @@
+export declare const SUPPORTED_CORE_RANGE = ">=3.10.0 <4.0.0";
+export declare function assertSupportedVersion(version: string): void;
+export declare function wrapSiteMetadata({ aliases, wrapper }: {
+    aliases: unknown;
+    wrapper: string;
+}): {
+    resolve: {
+        alias: {
+            "@theme/SiteMetadata": string;
+            "@myog-original/SiteMetadata": string;
+        };
+    };
+};

package/lib/siteMetadata.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_CORE_RANGE = void 0;
+exports.assertSupportedVersion = assertSupportedVersion;
+exports.wrapSiteMetadata = wrapSiteMetadata;
+const node_path_1 = require("node:path");
+const options_1 = require("./options");
+exports.SUPPORTED_CORE_RANGE = ">=3.10.0 <4.0.0";
+function assertSupportedVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match || Number(match[1]) !== 3 || Number(match[2]) < 10) {
+        throw new Error(`[${options_1.PLUGIN_NAME}] Docusaurus ${version} is not supported. Use a stable @docusaurus/core ${exports.SUPPORTED_CORE_RANGE} release or remove this plugin and use the manual guide at https://myog.social/docs/docusaurus. The SiteMetadata integration requires the tested theme alias and App render-order contracts.`);
+    }
+}
+function wrapSiteMetadata({ aliases, wrapper }) {
+    const resolved = aliases;
+    const original = resolved?.["@theme/SiteMetadata"];
+    if (!resolved ||
+        Array.isArray(resolved) ||
+        typeof original !== "string" ||
+        !(0, node_path_1.isAbsolute)(original) ||
+        original === wrapper ||
+        resolved["@myog-original/SiteMetadata"] !== undefined) {
+        throw new Error(`[${options_1.PLUGIN_NAME}] Cannot wrap the resolved @theme/SiteMetadata alias safely. Use a supported Docusaurus release (>=3.10.0 <4.0.0) and remove competing SiteMetadata alias remaps, or remove this plugin and use https://myog.social/docs/docusaurus. No fallback is substituted because it could discard your site's metadata.`);
+    }
+    return {
+        resolve: {
+            alias: {
+                "@theme/SiteMetadata": wrapper,
+                "@myog-original/SiteMetadata": original,
+            },
+        },
+    };
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "docusaurus-plugin-myog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Adds a MyOG.social og:image and twitter:image to every Docusaurus page, generated from each page's URL",
+  "keywords": [
+    "docusaurus",
+    "docusaurus-plugin",
+    "open-graph",
+    "og-image",
+    "twitter-card",
+    "social-card"
+  ],
+  "homepage": "https://myog.social/docs/docusaurus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MyOG-social/docusaurus-plugin-myog.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MyOG-social/docusaurus-plugin-myog/issues"
+  },
+  "license": "MIT",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": ">=3.10.0 <4.0.0",
+    "@docusaurus/types": ">=3.10.0 <4.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@docusaurus/types": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.14",
+    "@docusaurus/module-type-aliases": "3.10.2",
+    "@docusaurus/types": "3.10.2",
+    "@types/bun": "1.2.16",
+    "@types/node": "24.0.0",
+    "@types/react": "19.3.0",
+    "prettier": "3.7.4",
+    "react": "19.3.1",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.server.json && tsc -p tsconfig.client.json",
+    "type-check": "tsc --noEmit",
+    "test": "bun run build && bun test tests",
+    "lint": "biome lint src tests",
+    "format": "prettier --write"
+  }
 }