tc39 · bakkot · Jun 27, 2024 · Jun 7, 2024 · Jun 7, 2024 · Jun 26, 2024
diff --git a/spec/index.html b/spec/index.html
@@ -3,6 +3,7 @@
 <title>Ecmarkup</title>
 <pre class="metadata">
 repository: https://github.com/tc39/ecmarkup
+desription: An HTML superset/Markdown subset source format for ECMAScript and related specifications
 copyright: false
 markEffects: true
 </pre>
@@ -69,6 +70,7 @@ <h1>Options</h1>
       <tr><td></td><td>`version`</td><td>Document version, for example "6&lt;sup>th&lt;/sup> Edition" (which renders like "6<sup>th</sup> Edition") or "Draft 1".</td></tr>
       <tr><td></td><td>`date`</td><td>Timestamp of document rendering, used for various pieces of boilerplate. Defaults to the value of <a href="https://reproducible-builds.org/docs/source-date-epoch/">the `SOURCE_DATE_EPOCH` environment variable</a> (as a number of second since the POSIX epoch) if it exists, otherwise to the current date and time.</td></tr>
       <tr><td></td><td>`shortname`</td><td>Document shortname, for example "ECMA-262". If present and `status` is "draft", `version` defaults to "Draft <var>shortname</var>".</td></tr>
+      <tr><td></td><td>`description`</td><td>Brief description to be used for link previews in social media and the like.</td></tr>
       <tr><td></td><td>`location`</td><td>URL of this document. Used in conjunction with the biblio file to support inbound references from other documents.</td></tr>
       <tr><td></td><td>`copyright`</td><td>Emit copyright and software license information. Boolean, default true.</td></tr>
       <tr><td></td><td>`contributors`</td><td>Contributors to this specification, i.e. those who own the copyright. If your proposal includes text from any Ecma specification, this should include "Ecma International".</td></tr>

diff --git a/src/Spec.ts b/src/Spec.ts
@@ -1438,6 +1438,41 @@ ${this.opts.multipage ? `<li><span>Navigate to/from multipage</span><code>m</cod
         this.doc.body.insertBefore(h1, this.doc.body.firstChild);
       }
     }
+
+    // opengraph tags
+    const metas = [...this.doc.querySelectorAll('meta')];
+    const insertMetaTag =
+      metas.length === 0
+        ? (node: HTMLMetaElement) => this.doc.head.prepend(node)
+        : (node: HTMLMetaElement) => metas[metas.length - 1].after(node);
+    if (!metas.some(n => n.getAttribute('property') === 'og:description')) {
+      const description =
+        this.opts.description ??
+        (this.doc.querySelector('emu-intro') ?? this.doc.querySelector('emu-clause'))?.textContent
+          ?.slice(0, 300)
+          .trim();
+      if (description) {
+        const meta = this.doc.createElement('meta');
+        meta.setAttribute('property', 'og:description');
+        meta.setAttribute('content', description);
+        insertMetaTag(meta);
+      }
+    }
+    if (!metas.some(n => n.getAttribute('property') === 'og:title')) {
+      const title = this.opts.title ?? this.doc.querySelector('title')?.textContent;
+      if (title) {
+        const meta = this.doc.createElement('meta');
+        meta.setAttribute('property', 'og:title');
+        meta.setAttribute('content', title);
+        insertMetaTag(meta);
+      }
+    }
+    if (!metas.some(n => n.getAttribute('property') === 'og:image')) {
+      const meta = this.doc.createElement('meta');
+      meta.setAttribute('property', 'og:image');
+      meta.setAttribute('content', 'https://tc39.es/ecmarkup/ecma-header.png');
+      insertMetaTag(meta);
+    }
   }
 
   private buildCopyrightBoilerplate() {

diff --git a/src/ecmarkup.ts b/src/ecmarkup.ts
@@ -27,6 +27,7 @@ export interface Options {
   version?: string;
   title?: string;
   shortname?: string;
+  description?: string;
   stage?: string | null;
   copyright?: boolean;
   date?: Date;

diff --git a/test/baselines/generated-reference/copyright.html b/test/baselines/generated-reference/copyright.html
@@ -1,5 +1,5 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<head><meta charset="utf-8"><meta property="og:image" content="https://tc39.es/ecmarkup/ecma-header.png"><meta property="og:title" content="test title!"><meta property="og:description" content="Test Clause"><title>test title!</title></head><body><div id="shortcuts-help">
 <ul>
   <li><span>Toggle shortcuts help</span><code>?</code></li>
   <li><span>Toggle "can call user code" annotations</span><code>u</code></li>

diff --git a/test/baselines/generated-reference/proposal-copyright.html b/test/baselines/generated-reference/proposal-copyright.html
@@ -1,5 +1,5 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<head><meta charset="utf-8"><meta property="og:image" content="https://tc39.es/ecmarkup/ecma-header.png"><meta property="og:title" content="test title!"><title>test title!</title></head><body><div id="shortcuts-help">
 <ul>
   <li><span>Toggle shortcuts help</span><code>?</code></li>
   <li><span>Toggle "can call user code" annotations</span><code>u</code></li>

diff --git a/test/baselines/generated-reference/shortname.html b/test/baselines/generated-reference/shortname.html
@@ -1,5 +1,5 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<head><meta charset="utf-8"><meta property="og:image" content="https://tc39.es/ecmarkup/ecma-header.png"><meta property="og:title" content="test title!"><title>test title!</title></head><body><div id="shortcuts-help">
 <ul>
   <li><span>Toggle shortcuts help</span><code>?</code></li>
   <li><span>Toggle "can call user code" annotations</span><code>u</code></li>

diff --git a/test/baselines/generated-reference/test.html b/test/baselines/generated-reference/test.html
@@ -1,5 +1,7 @@
 <!doctype html>
-<head><meta charset="utf-8">
+<head><meta charset="utf-8"><meta property="og:image" content="https://tc39.es/ecmarkup/ecma-header.png"><meta property="og:title" content="Ecmarkup Test Document"><meta property="og:description" content="Intro
+
+    Sub Intro">
 <link rel="stylesheet" href="css/elements.css">
 <script src="ecmarkup.js"></script>
 <title>Ecmarkup Test Document</title></head><body><div id="shortcuts-help">

diff --git a/test/baselines/generated-reference/title.html b/test/baselines/generated-reference/title.html
@@ -1,5 +1,5 @@
 <!doctype html>
-<head><meta charset="utf-8"><title>test title!</title></head><body><div id="shortcuts-help">
+<head><meta charset="utf-8"><meta property="og:image" content="https://tc39.es/ecmarkup/ecma-header.png"><meta property="og:title" content="test title!"><meta property="og:description" content="a test document"><title>test title!</title></head><body><div id="shortcuts-help">
 <ul>
   <li><span>Toggle shortcuts help</span><code>?</code></li>
   <li><span>Toggle "can call user code" annotations</span><code>u</code></li>

diff --git a/test/baselines/sources/title.html b/test/baselines/sources/title.html
@@ -1,5 +1,6 @@
 <pre class=metadata>
 title:     test title!
+description: a test document
 status:    draft
 version:   Draft 1
 toc:       false