Add EPUB and Word (.docx) export pipeline by taylorarndt · Pull Request #172 · Community-Access/git-going-with-github

taylorarndt · 2026-03-08T05:25:47Z

What this does

Adds automated EPUB and Word export from the docs/ folder.

Formats

EPUB — for Kindle, Apple Books, Kobo, any e-reader
Word (.docx) — for screen reader users on Windows, printing, or editing

How it works

scripts/build-epub.js preprocesses all 44 docs (strips broken links, podcast callouts) then runs pandoc
.github/workflows/build-epub.yml triggers automatically whenever docs/** changes on main
Both files are committed back to the repo and uploaded as 90-day artifacts

Triggered by

Any push to main that changes docs/**, epub/metadata.yaml, epub/epub.css, or scripts/build-epub.js
Manual via workflow_dispatch

- scripts/build-epub.js — builds a single EPUB from all 44 docs/ files - epub/metadata.yaml — title, author, language, TOC depth, CC BY 4.0 rights - epub/epub.css — clean typesetting (serif body, sans headings, code blocks, tables) - .github/workflows/build-epub.yml — auto-builds on docs/ changes, uploads as artifact - npm run build:epub script added to package.json EPUB is generated locally but not committed (in .gitignore). The workflow artifact is retained for 90 days. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Remove WeasyPrint/PDF (dependency issues) - Add Word .docx output using pandoc --to docx - Both formats built from same preprocessed markdown - CI workflow updated: uploads EPUB and Word artifacts (90-day) - .gitignore updated for .docx - pdf.css kept for reference but not used in build Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-03-08T05:26:01Z

Copilot

Pull request overview

This PR adds an automated EPUB and Word (.docx) export pipeline for the docs/ folder, enabling accessible reading on e-readers, screen readers, and for printing. The build script preprocesses 44+ markdown files (stripping podcast callouts, rewriting internal links) and runs pandoc to generate both formats. A GitHub Actions workflow automates the build on docs changes.

Changes:

New scripts/build-epub.js build script that preprocesses markdown files and invokes pandoc for EPUB and Word output
New .github/workflows/build-epub.yml workflow that triggers on docs changes, builds both formats, uploads artifacts, and commits outputs
New epub/ directory with metadata, EPUB CSS, and PDF CSS files; updated .gitignore and package.json

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`scripts/build-epub.js`	Core build script: reads docs, preprocesses markdown, invokes pandoc for EPUB and DOCX
`.github/workflows/build-epub.yml`	CI workflow: triggers on docs changes, installs pandoc, runs build, uploads artifacts, commits outputs
`epub/metadata.yaml`	Pandoc metadata for the EPUB/DOCX (title, author, TOC settings)
`epub/epub.css`	Stylesheet for the EPUB output
`epub/pdf.css`	Stylesheet for future PDF output (not yet used by build script)
`.gitignore`	Ignores generated `.epub` and `.docx` output files
`package.json`	Adds `build:epub` npm script

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-08T05:30:42Z

scripts/build-epub.js

+  //    Pattern: > **Listen to Episode N:** ... line(s)
+  content = content.replace(/^>[ \t]*\*\*Listen to Episode[^\n]*\n/gm, '');


The podcast callout regex only removes the > **Listen to Episode... line, but the actual callouts in the docs are preceded by a standalone > line (e.g., docs/00-pre-workshop-setup.md line 2). This leaves an orphaned empty blockquote marker > in the preprocessed output, which will render as an empty blockquote element in the EPUB/DOCX.

Consider expanding the pattern to also match and remove the preceding empty blockquote line, e.g. matching ^>\s*\n^>[ \t]*\*\*Listen to Episode[^\n]*\n.

Suggested change

// Pattern: > **Listen to Episode N:** ... line(s)

content = content.replace(/^>[ \t]*\*\*Listen to Episode[^\n]*\n/gm, '');

// Pattern:

// >

// > **Listen to Episode N:** ... line

content = content.replace(/^>\s*\n^>[ \t]*\*\*Listen to Episode[^\n]*\n/gm, '');

Copilot · 2026-03-08T05:30:43Z

scripts/build-epub.js

+#!/usr/bin/env node
+/**
+ * Build EPUB from docs/ markdown files using Pandoc.
+ * Outputs: epub/git-going-with-github.epub


The file-level doc comment says "Outputs: epub/git-going-with-github.epub" but the script also outputs epub/git-going-with-github.docx. The docstring should mention both outputs.

Suggested change

* Outputs: epub/git-going-with-github.epub

* Outputs: epub/git-going-with-github.epub, epub/git-going-with-github.docx

Copilot · 2026-03-08T05:30:43Z

scripts/build-epub.js

+  const size = (fs.statSync(EPUB_OUT).size / 1024).toFixed(1);
+  console.log(`\nEPUB written: epub/git-going-with-github.epub (${size} KB)`);
+} catch (err) {
+  console.error('\nPandoc EPUB failed. Is pandoc installed? Run: brew install pandoc');


The error message suggests brew install pandoc as the install command, but the CI workflow runs on ubuntu-latest where apt-get install pandoc is the correct command. This could be confusing for contributors who encounter the error in CI. Consider making the suggestion platform-aware, or at minimum mentioning both brew install pandoc (macOS) and sudo apt-get install pandoc (Linux).

Copilot · 2026-03-08T05:30:43Z

.github/workflows/build-epub.yml

+      - name: Commit outputs to repository
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add epub/git-going-with-github.epub epub/git-going-with-github.docx
+          if [ -n "$(git status --porcelain)" ]; then
+            git commit -m "chore: rebuild EPUB and Word from latest docs"
+            git push
+          else
+            echo "No changes to commit"
+          fi


The .gitignore file (lines 168-169) ignores epub/git-going-with-github.epub and epub/git-going-with-github.docx, but the workflow step at line 55 runs git add on those same files. Since they are gitignored, git add will silently skip them (they won't be staged), the porcelain check will find no changes, and the commit/push will never happen.

You need to either:

Remove these entries from .gitignore so the files can be committed, or

Use git add -f epub/git-going-with-github.epub epub/git-going-with-github.docx to force-add ignored files, or

Remove the commit step entirely and rely solely on the artifact uploads.

Copilot · 2026-03-08T05:30:43Z

scripts/build-epub.js

+  const size = (fs.statSync(EPUB_OUT).size / 1024).toFixed(1);
+  console.log(`\nEPUB written: epub/git-going-with-github.epub (${size} KB)`);
+} catch (err) {
+  console.error('\nPandoc EPUB failed. Is pandoc installed? Run: brew install pandoc');


If the EPUB pandoc build fails, process.exit(1) on line 134 terminates the process immediately without cleaning up the temporary directory created at line 23. The fs.rmSync(TMP, ...) cleanup in the finally block (line 158-159) only covers the docx build.

Consider wrapping both builds in a single try/finally, or adding cleanup before process.exit(1) on line 134.

Suggested change

console.error('\nPandoc EPUB failed. Is pandoc installed? Run: brew install pandoc');

console.error('\nPandoc EPUB failed. Is pandoc installed? Run: brew install pandoc');

try {

fs.rmSync(TMP, { recursive: true, force: true });

} catch (cleanupErr) {

// ignore cleanup errors

}

Copilot · 2026-03-08T05:30:44Z

scripts/build-epub.js

+  '--split-level=1',
+  '--syntax-highlighting=tango',


--syntax-highlighting=tango (line 122) and --split-level=1 (line 121) do not appear to be valid pandoc command-line options. The standard pandoc equivalents are --highlight-style=tango and --epub-chapter-level=1 respectively. Note that epub-chapter-level: 1 is already set in epub/metadata.yaml, so the command-line flag may be redundant once corrected.

If using a very recent pandoc version that introduced --split-level, please verify by running pandoc --help | grep split-level in the CI environment (Ubuntu apt pandoc). The pandoc version from apt on ubuntu-latest is often older and may not support newer flags.

Suggested change

'--split-level=1',

'--syntax-highlighting=tango',

'--epub-chapter-level=1',

'--highlight-style=tango',

taylorarndt and others added 3 commits March 7, 2026 23:02

fix: rename workflow to Build EPUB and Word

e8d7707

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 8, 2026 05:25

taylorarndt requested a review from accesswatch as a code owner March 8, 2026 05:25

Copilot started reviewing on behalf of taylorarndt March 8, 2026 05:26 View session

taylorarndt closed this Mar 8, 2026

taylorarndt merged commit 2126847 into main Mar 8, 2026
4 of 5 checks passed

taylorarndt deleted the epub-typesetting branch March 8, 2026 05:28

Copilot AI reviewed Mar 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add EPUB and Word (.docx) export pipeline#172

Add EPUB and Word (.docx) export pipeline#172
taylorarndt merged 3 commits intomainfrom
epub-typesetting

taylorarndt commented Mar 8, 2026

Uh oh!

github-actions bot commented Mar 8, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		// Pattern: > Listen to Episode N: ... line(s)
		content = content.replace(/^>[ \t]\\Listen to Episode[^\n]\n/gm, '');

	* Outputs: epub/git-going-with-github.epub
	* Outputs: epub/git-going-with-github.epub, epub/git-going-with-github.docx

-  console.error('\nPandoc EPUB failed. Is pandoc installed? Run: brew install pandoc');
+  console.error('\nPandoc EPUB failed. Is pandoc installed? Run: brew install pandoc');
+  try {
+    fs.rmSync(TMP, { recursive: true, force: true });
+  } catch (cleanupErr) {
+    // ignore cleanup errors
+  }

Conversation

taylorarndt commented Mar 8, 2026

What this does

Formats

How it works

Triggered by

Uh oh!

github-actions bot commented Mar 8, 2026

Peer Review Assigned

For @accesswatch:

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants