Skip to content

main: add "Other versions" links to frontmatter of HTML-rendered specs #4401

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 3, 2025
Merged

main: add "Other versions" links to frontmatter of HTML-rendered specs #4401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions scripts/md2html/build.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,10 @@ cp -p node_modules/respec/builds/respec-w3c.* $deploydir/js/

latest=$(git describe --abbrev=0 --tags)

allVersions=$(ls -1 versions/[23456789].*.md | grep -v -e "\-editors" | sort -r)

if [ -z "$1" ]; then
specifications=$(ls -1 versions/[23456789].*.md | grep -v -e "\-editors" | sort -r)
specifications=$allVersions
elif [ "$1" = "latest" ]; then
specifications=$(ls -1 versions/$latest.md)
elif [ "$1" = "src" ]; then
Expand Down Expand Up @@ -53,7 +55,7 @@ for specification in $specifications; do

echo === Building $version to $destination

node scripts/md2html/md2html.js --maintainers $maintainers $specification > $tempfile
node scripts/md2html/md2html.js --maintainers $maintainers $specification "$allVersions" > $tempfile
Copy link
Contributor

@duncanbeevers duncanbeevers Mar 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider using a yargs array, rather than overloading the positional argument.

diff --git a/scripts/md2html/build.sh b/scripts/md2html/build.sh
index b40a1a12..c0ef1654 100755
--- a/scripts/md2html/build.sh
+++ b/scripts/md2html/build.sh
@@ -55,7 +55,11 @@ for specification in $specifications; do
 
   echo === Building $version to $destination
 
-  node scripts/md2html/md2html.js --maintainers $maintainers $specification "$allVersions" > $tempfile
+  node scripts/md2html/md2html.js \
+    --maintainers $maintainers \
+    --all-versions $allVersions -- \
+    $specification > $tempfile
+
   npx respec --no-sandbox --use-local --src $tempfile --out $destination
   rm $tempfile
 
diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js
index c3ff2862..2873b3d4 100644
--- a/scripts/md2html/md2html.js
+++ b/scripts/md2html/md2html.js
@@ -55,6 +55,9 @@ let argv = require('yargs')
     .alias('m','maintainers')
     .describe('maintainers','path to MAINTAINERS.md')
     .demandCommand(1)
+    .array('all-versions')
+    .alias('av', 'all-versions')
+    .describe('all-versions', 'List of all versions of the specification, used for inter-version linking')
     .argv;
 const abstract = 'What is the OpenAPI Specification?';
 let maintainers = [];
@@ -77,7 +80,7 @@ const md = require('markdown-it')({
 });
 
 function preface(title,options) {
-    const otherVersions = options._[1].split("\n").map(v => path.basename(v,'.md')).filter(v => v !== options.subtitle);
+    const otherVersions = options['all-versions'].map(v => path.basename(v,'.md')).filter(v => v !== options.subtitle)
     const respec = {
         specStatus: "base",
         latestVersion: "https://spec.openapis.org/oas/latest.html",

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion.

If the command-line interface of md2html were to survive, an array of positional parameters could be seen as more elegant, and preferable to a dash-dash option because allVersions is not optional.

In #4234 we plan to move the whole md2html stuff to a separate repository and reshape it into a GitHub action, which will remove the current yargs solution along with all bash parts and replace it with a JS function md2html(spec,editors,formerEditors,allVersions) or similar. So I don't want to invest into the current command-line interface.

npx respec --no-sandbox --use-local --src $tempfile --out $destination
rm $tempfile

Expand Down
9 changes: 9 additions & 0 deletions scripts/md2html/md2html.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ const md = require('markdown-it')({
});

function preface(title,options) {
const otherVersions = options._[1].split("\n").map(v => path.basename(v,'.md')).filter(v => v !== options.subtitle);
const respec = {
specStatus: "base",
latestVersion: "https://spec.openapis.org/oas/latest.html",
Expand All @@ -96,6 +97,14 @@ function preface(title,options) {
height: 48,
url: "https://openapis.org/"}],
otherLinks: [
{
key: "Other versions:",
data: otherVersions.map(v => {
return {
href: `https://spec.openapis.org/oas/v${v}.html`
}
})
},
{
key: "Participate",
data: [
Expand Down
2 changes: 1 addition & 1 deletion tests/md2html/fixtures/basic-new.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"John Doe "},{"name":"Jane Doe "}],"formerEditors":[{"name":"Foo Bar "}],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"John Doe "},{"name":"Jane Doe "}],"formerEditors":[{"name":"Foo Bar "}],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Other versions:","data":[{"href":"https://spec.openapis.org/oas/v31.0.0.html"},{"href":"https://spec.openapis.org/oas/v30.0.0.html"}]},{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
<script>
window.dataLayer = window.dataLayer || [];
Expand Down
2 changes: 1 addition & 1 deletion tests/md2html/fixtures/basic-old.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"Foo Bar "}],"formerEditors":[],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>OpenAPI Specification v30.0.1 | Introduction, Definitions, &amp; More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs."><meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"Foo Bar "}],"formerEditors":[],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Other versions:","data":[{"href":"https://spec.openapis.org/oas/v31.0.0.html"},{"href":"https://spec.openapis.org/oas/v30.0.0.html"}]},{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script><!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
<script>
window.dataLayer = window.dataLayer || [];
Expand Down
10 changes: 6 additions & 4 deletions tests/md2html/md2html.test.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { readdirSync, readFileSync } from "node:fs";
import { exec } from "node:child_process";
import { execFile } from "node:child_process";
import { resolve } from "node:path";
import { describe, test, expect } from "vitest";
import assert from "node:assert";
Expand All @@ -13,12 +13,13 @@ describe("md2html", async () => {
const expected = readFileSync(
folder + entry.name.replace(".md", ".html"),
"utf8",
);
);
const output = await md2html(
[
"--maintainers",
entry.name.replace(".md", ".maintainers"),
entry.name,
"path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md",
],
folder,
);
Expand All @@ -29,8 +30,9 @@ describe("md2html", async () => {

function md2html(args, cwd) {
return new Promise((res) => {
exec(
`node ${resolve("./scripts/md2html/md2html.js")} ${args.join(" ")}`,
execFile(
"node",
[`${resolve("./scripts/md2html/md2html.js")}`, ...args],
{ cwd },
(error, stdout, stderr) => {
res({
Expand Down