diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index a62c09afc..d8b16c809 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -26,7 +26,7 @@ jobs: - name: Build docs run: | npm ci - npm run html + npm run build git config user.name ${GITHUB_ACTOR} git config user.email ${PUSHER_EMAIL} git add docs/* diff --git a/README.md b/README.md index e36cd9d78..2358e700f 100644 --- a/README.md +++ b/README.md @@ -23,15 +23,8 @@ Documents are generated from a Markdown source using Node.js modules described [ To view mathematical formulas, install pandoc as explained in the section on [Document Conventions](odata-data-aggregation-ext/1%20Introduction.md). This is invoked by the Node.js module [`lib/pandoc.js`](lib/pandoc.js). -Clone this repository, run `npm install` and `npm start` to start a Node.js server and access the HTML pages at, for example, `http://localhost:8080/odata-data-aggregation-ext` (see [`lib/server.js`](lib/server.js)). +Clone this repository, run `npm install` and `npm start` to start a Node.js server and access the HTML pages at `http://localhost:8080` (see [`lib/server.js`](lib/server.js)). Run `npm run build` to build HTML and Markdown files for publication on github.io (see [`lib/build.js`](lib/build.js)). -Run `npm run pdf` to convert the HTML files into PDF files (using puppeteer, see [`lib/pdf.js`](lib/pdf.js)). - -## To Do - -- [ ] Check MD/HTML for broken and inconsistent links (similar to what we currently do with the `ExtractHyperlinksToExcel` Word macro) - - [x] Check for use of undefined anchors - - [ ] Check for hyperlinks with the same link target and different texts - - [ ] Check for hyperlinks with the same text and different link targets +Run `npm run pdf` to convert the HTML files into PDF files (using puppeteer, see [`lib/pdf.js`](lib/build-pdf.js)). diff --git a/lib/README.md b/lib/README.md index 051db54bd..09c5ae282 100644 --- a/lib/README.md +++ b/lib/README.md @@ -74,7 +74,7 @@ proc.stdout.pipe(«HTML file»); new Number("odata-data-aggregation-ext").build(proc.stdin); ``` -The HTML file uses CSS stylesheets contained in the [`doc/*/styles`](../doc/odata-data-aggregation-ext/styles) subfolder in order to render keywords in the same font (MathJax Typewriter) whether they occur standalone or in a formula: +The HTML file uses CSS stylesheets contained in the [`docs/*/styles`](../docs/odata-data-aggregation-ext/styles) subfolder in order to render keywords in the same font (MathJax Typewriter) whether they occur standalone or in a formula: | Keyword occurs | Markdown source | Rendered result | | ------------------ | ------------------------------------ | ------------------------------------ | @@ -83,14 +83,14 @@ The HTML file uses CSS stylesheets contained in the [`doc/*/styles`](../doc/odat A monospaced font (Courier New) is used for OData requests and their JSON or XML responses. -[`npm start`](server.js) starts a web server that serves such HTML files and the static `.css` files without writing intermediate files. This allows authors to see the effects of every change to the source folder in the working tree after refreshing the browser. +[`npm start`](server.js) starts a web server that serves such HTML files and the static `.css` files without writing intermediate files. This allows authors to see the effects of every change to the source folder in the working tree after saving the source files which triggers a browser auto-refresh. -The [`pdf.js`](pdf.js) module uses an embedded browser ([`puppeteer`](https://github.com/puppeteer/puppeteer#puppeteer)) to convert the HTML file into a PDF file with OASIS headers and footers. +The [`pdf.js`](pdf.js) module uses a headless browser ([`puppeteer`](https://github.com/puppeteer/puppeteer#puppeteer)) to convert the HTML file into a PDF file with OASIS headers and footers. The following scripts can be executed manually or as part of a GitHub Action: -- [`npm run build`](build.js) runs the conversion and writes the Markdown output as well as the HTML output into the [`doc/*`](../doc/odata-data-aggregation-ext) folder. The Markdown file starts with a byte-order mark (`EF BB BF`) so that it is recognized as UTF-8 when loaded from github.io. -- [`npm run pdf`](build-pdf.mjs) runs the PDF conversion and writes the PDF document into the [`doc/*`](../doc/odata-data-aggregation-ext) folder. +- [`npm run build`](build.js) runs the conversion and writes the Markdown output as well as the HTML output into the [`docs/*`](../docs) folder. The Markdown file starts with a byte-order mark (`EF BB BF`) so that it is recognized as UTF-8 when loaded from github.io. +- [`npm run pdf`](build-pdf.mjs) runs the PDF conversion and writes the PDF document into the [`docs/*`](../docs) folder. - [`npm test`](../test) runs a test suite. ## A note on diagrams diff --git a/package.json b/package.json index f8e595e30..488fcff8e 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,7 @@ "description": "", "main": "number.js", "scripts": { - "build": "npm run html && npm run pdf", - "html": "node lib/build.js", + "build": "node lib/build.js", "pdf": "node lib/build-pdf.js", "start": "node lib/server", "test": "c8 -r html -r text mocha",