Rendered spec, generate latest.html and add DOCTYPE (#2607)

MikeRalphson · web-flow · commit 3d2c0440ec19 · 2021-06-10T10:30:53.000-06:00
* fix: md2html/build.sh specify bash in shebang

Signed-off-by: Mike Ralphson &lt;mike.ralphson@gmail.com&gt;

* fix: changes for abstract title in md2html.js

Signed-off-by: Mike Ralphson &lt;mike.ralphson@gmail.com&gt;
diff --git a/scripts/md2html/build.sh b/scripts/md2html/build.sh
@@ -1,6 +1,9 @@
-#!/bin/sh
+#!/bin/bash
 
-# run this script from the root of the repo
+# Author: @MikeRalphson
+
+# run this script from the root of the repo. It is designed to be run by a GitHub workflow.
+# It contains bashisms
 
 mkdir -p deploy/oas
 mkdir -p deploy/js
diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js
@@ -26,6 +26,7 @@ let argv = require('yargs')
     .describe('maintainers','path to MAINTAINERS.md')
     .require(1)
     .argv;
+const abstract = 'What is the OpenAPI Specification?';
 let maintainers = [];
 let emeritus = [];
 
@@ -66,14 +67,14 @@ function preface(title,options) {
         includePermalinks: true
     };
 
-    let preface = `<html lang="en"><head><meta charset="UTF-8"><title>${md.utils.escapeHtml(title)}</title>`;
+    let preface = `<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>${md.utils.escapeHtml(title)}</title>`;
 
     // SEO
     preface += '<meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs.">';
     preface += '<link rel="canonical" href="https://spec.openapis.org/oas/latest.html" />';
 
     if (options.respec) {
-        preface += '<script src="https://spec.openapis.org/js/respec-oai.js" class="remove"></script>';
+        preface += '<script src="../js/respec-oai.js" class="remove"></script>';
         preface += `<script class="remove">var respecConfig = ${JSON.stringify(respec)};</script>`;
         preface += fs.readFileSync('./analytics/google.html','utf8');
         preface += '</head><body>';
@@ -90,7 +91,8 @@ function preface(title,options) {
         preface += 'pre { background-color: #f6f8fa !important; }';
         preface += fs.readFileSync(path.resolve(__dirname,'gist.css'),'utf8').split('\n').join(' ');
         preface += '</style>';
-        preface += '<section id="abstract">';
+        preface += `<h1 id="title">${title.split('|')[0]}</h1>`;
+        preface += `<section id="abstract" title="${abstract}">`;
         preface += 'The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.';
         preface += '</section>';
         preface += '<section class="notoc" id="sotd">';
