Build github.io pages with pandoc instead of Jekyll (#248)

oasis-tcs · Apr 10, 2024 · 47b31bf · 47b31bf
1 parent 4bf7e89
commit 47b31bf
Show file tree

Hide file tree

Showing 12 changed files with 354 additions and 4 deletions.
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -0,0 +1,54 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Build GitHub Pages using pandoc
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Setup pandoc
+        uses: nikeee/setup-pandoc@v1
+        with:
+          pandoc-version: 3.1.12.2
+      - name: Build with pandoc
+        run: |
+          npm ci
+          npm run pages "OASIS OData TC"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
@@ -24,7 +24,7 @@ jobs:
         run: |
           npm ci
           npm run build --if-present
-          npm test
+          npm test test/csdl2markdown.test.js
           git diff --exit-code vocabularies
         env:
           CI: true
diff --git a/assets/styles/style.css b/assets/styles/style.css
diff --git a/assets/template.html b/assets/template.html
@@ -0,0 +1,78 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$>
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+$for(author-meta)$
+  <meta name="author" content="$author-meta$" />
+$endfor$
+$if(date-meta)$
+  <meta name="dcterms.date" content="$date-meta$" />
+$endif$
+$if(keywords)$
+  <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
+$endif$
+$if(description-meta)$
+  <meta name="description" content="$description-meta$" />
+$endif$
+  <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
+  <style>
+    $styles.html()$
+  </style>
+$for(css)$
+  <link rel="stylesheet" href="$css$" />
+$endfor$
+$for(header-includes)$
+  $header-includes$
+$endfor$
+$if(math)$
+$if(mathjax)$
+  <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
+$endif$
+  $math$
+$endif$
+</head>
+<body>
+$for(include-before)$
+$include-before$
+$endfor$
+<div class="container-lg px-3 my-5 markdown-body">
+$if(title)$
+<header id="title-block-header">
+<h1 class="title">$title$</h1>
+$if(subtitle)$
+<p class="subtitle">$subtitle$</p>
+$endif$
+$for(author)$
+<p class="author">$author$</p>
+$endfor$
+$if(date)$
+<p class="date">$date$</p>
+$endif$
+$if(abstract)$
+<div class="abstract">
+<div class="abstract-title">$abstract-title$</div>
+$abstract$
+</div>
+$endif$
+</header>
+$endif$
+$if(toc)$
+<nav id="$idprefix$TOC" role="doc-toc">
+$if(toc-title)$
+<h2 id="$idprefix$toc-title">$toc-title$</h2>
+$endif$
+$table-of-contents$
+</nav>
+$endif$
+$body$
+</div>
+$for(include-after)$
+$include-after$
+$endfor$
+$for(include-script)$
+$include-script$
+$endfor$
+</body>
+</html>
diff --git a/lib/md2html.js b/lib/md2html.js
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const filter = require("pandoc-filter");
+
+filter.stdio(function ({ t, c }, format, meta) {
+  if (t === "Link" && !/^https?:\/\//.test(c[2][0])) {
+    c[2][0] = c[2][0].replace(/\.md(?=$|#)/, ".html");
+    return filter.Link(...c);
+  }
+});
diff --git a/lib/pages.js b/lib/pages.js
@@ -0,0 +1,45 @@
+const pandoc = require("./pandoc");
+const fs = require("fs");
+
+const VOCAB = require("../package.json").name;
+const REPO = process.argv[process.argv.length - 1];
+
+function file(dir, title, filename) {
+  console.log(`${dir}/${filename}`);
+  pandoc(
+    {
+      stdin: fs.createReadStream(`${__dirname}/../${dir}/${filename}`),
+      stdout: fs.createWriteStream(
+        `_site/${dir}/${filename === "README.md" ? "index.html" : filename.replace(/\.md$/, ".html")}`,
+      ),
+    },
+    {
+      "-c": `/${VOCAB}/styles/style.css`,
+      "-F": `${__dirname}/md2html.js`,
+      "-M": `title=${REPO}${title ? " - " + title : ""}`,
+      "--template": "assets/template",
+    },
+  );
+}
+
+function directory(dir, title) {
+  if (fs.existsSync(`${__dirname}/../${dir}`)) {
+    fs.cpSync(`${__dirname}/../${dir}`, `_site/${dir}`, {
+      recursive: true,
+    });
+    fs.readdirSync(`${__dirname}/../${dir}`)
+      .filter((fn) => fn.endsWith(".md"))
+      .forEach(function (filename) {
+        file(dir, title, filename);
+      });
+  }
+}
+
+fs.cpSync(`${__dirname}/../assets/styles`, `_site/styles`, {
+  recursive: true,
+});
+
+file(".", "", "README.md");
+directory("docs", "Documents");
+directory("examples", "Examples");
+directory("vocabularies", "Vocabularies");
diff --git a/lib/pandoc.js b/lib/pandoc.js
@@ -0,0 +1,41 @@
+const { spawn } = require("child_process");
+
+function pandoc({ stdin, stdout }, options = {}) {
+  var mermaidOptions = { startOnLoad: false, ...options.mermaid };
+  delete options.mermaid;
+  var opts = [
+    "-f",
+    "gfm+tex_math_dollars",
+    "-t",
+    "html",
+    "--mathjax",
+    "-s",
+    "--eol=lf",
+    "--wrap=none",
+    "-V",
+    `include-script=<script type="module">
+	document.addEventListener("DOMContentLoaded", function() {
+		document.querySelectorAll(".mermaid").forEach(function(pre) {
+			pre.style.width = pre.getClientRects()[0].width + "px";
+		});
+	});
+	import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
+	mermaid.initialize(${JSON.stringify(mermaidOptions)});
+	mermaid.run({nodes: document.querySelectorAll(".mermaid code")});
+</script>`,
+  ];
+  for (var param in options)
+    [].concat(options[param]).forEach(function (value) {
+      if (value && param.startsWith("--")) opts.push(param + "=" + value);
+      else if (value && param.startsWith("-")) opts.push(param, value);
+      else opts.push(param);
+    });
+  var proc = spawn("pandoc", opts);
+  proc.stderr.on("data", function (err) {
+    console.error(err.toString());
+  });
+  proc.stdout.pipe(stdout);
+  stdin.on("error", console.error).pipe(proc.stdin);
+}
+
+module.exports = pandoc;
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -14,10 +14,16 @@
   "bin": {
     "odata-vocab2md": "lib/cli.js"
   },
-  "main": "lib/csdl2markdown.js",
+  "exports": {
+    ".": "./lib/csdl2markdown.js",
+    "./pandoc": "./lib/pandoc.js",
+    "./pages": "./lib/pages.js",
+    "./template": "./assets/template.html"
+  },
   "dependencies": {
     "colors": "^1.4.0",
-    "odata-csdl": "^0.9.5"
+    "odata-csdl": "^0.9.5",
+    "pandoc-filter": "^2.2.0"
   },
   "devDependencies": {
     "c8": "^9.1.0",
@@ -26,6 +32,7 @@
   },
   "scripts": {
     "build": "node lib/transform.js",
+    "pages": "node lib/pages.js",
     "test": "c8 -r html -r text mocha",
     "watch": "mocha --watch"
   },

diff --git a/test/pandoc.test.js b/test/pandoc.test.js
@@ -0,0 +1,34 @@
+const assert = require("assert");
+const fs = require("fs");
+const pandoc = require("../lib/pandoc");
+const { PassThrough } = require("stream");
+
+describe("OASIS voc build", function () {
+  it("Pandoc", function () {
+    var html = "";
+    pandoc(
+      {
+        stdin: fs.createReadStream(`${__dirname}/test-data/pandoc.md`),
+        stdout: new PassThrough()
+          .on("data", function (chunk) {
+            html += chunk.toString();
+          })
+          .on("end", function () {
+            assert.deepStrictEqual(
+              html.split(/\r\n|\r|\n/),
+              fs
+                .readFileSync(`${__dirname}/test-data/pandoc.html`)
+                .toString()
+                .split(/\r\n|\r|\n/),
+            );
+          }),
+      },
+      {
+        "-c": "style.css",
+        "-F": `${__dirname}/../lib/md2html.js`,
+        "-M": "title=Test",
+        "--template": `${__dirname}/../assets/template`,
+      },
+    );
+  });
+});