tc39 · bakkot · Jun 27, 2024 · Jun 7, 2024 · Jun 7, 2024 · Jun 26, 2024
diff --git a/ecma-logo.png b/ecma-logo.png
diff --git a/package.json b/package.json
@@ -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",

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,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() {

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

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

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

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

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

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