add support for opengraph tags (#598)

Author: bakkot

ecma-logo.png

@@ -7,7 +7,7 @@
 	"scripts": {
 		"build": "tsc -sourceMap -declarationMap",
 		"build-release": "tsc",
-		"build-spec": "mkdir -p docs && node bin/ecmarkup.js spec/index.html docs/index.html --assets-dir=docs",
+		"build-spec": "mkdir -p docs && node bin/ecmarkup.js spec/index.html docs/index.html --assets-dir=docs && cp ecma-logo.png docs/",
 		"prepack": "safe-publish-latest && npm run build-release",
 		"format-spec": "node bin/emu-format.js --write spec/index.html",
 		"test": "mocha",

package.json

@@ -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>

spec/index.html

@@ -1438,6 +1438,42 @@ ${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-logo.png');
+      insertMetaTag(meta);
+    }
   }
 
   private buildCopyrightBoilerplate() {

src/Spec.ts

@@ -27,6 +27,7 @@ export interface Options {
   version?: string;
   title?: string;
   shortname?: string;
+  description?: string;
   stage?: string | null;
   copyright?: boolean;
   date?: Date;

src/ecmarkup.ts

@@ -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-logo.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>

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-logo.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>

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-logo.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>

test/baselines/generated-reference/shortname.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-logo.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">

test/baselines/generated-reference/test.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-logo.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>