Skip to content

Fix asciidoctor v4 ESM import to unbreak Publish to website - #640

Merged
rrrutledge merged 1 commit into
mainfrom
fix-asciidoctor-v4-esm-import
Sep 8, 2026
Merged

Fix asciidoctor v4 ESM import to unbreak Publish to website#640
rrrutledge merged 1 commit into
mainfrom
fix-asciidoctor-v4-esm-import

Conversation

@rrrutledge

Copy link
Copy Markdown
Contributor

What broke

The Publish to website workflow has failed on every push to main since the asciidoctor dependency was bumped from 3.x to 4.0.2 (Dependabot #628, merged 2026-07-14). The build dies at module load with:

scripts/generate_learning_path_markdown.js:4
import asciidoctor  from 'asciidoctor'
       ^^^^^^^^^^^
SyntaxError: The requested module 'asciidoctor' does not provide an export named 'default'

asciidoctor 4.x is a breaking API change: it dropped the default export and the asciidoctor() factory function in favor of named ESM exports (convert, load, etc.), and convert is now async.

As a result the learning-path content has not republished to innersourcecommons.org for roughly two months.

The fix

  • Import the named convert export instead of the removed default factory.
  • await the two convert(...) call sites (both already sit inside async callbacks, so no other restructuring is needed).

Why the output is safe

v4's convert produces byte-for-byte identical HTML to v3 on the learning-path articles (verified by converting the same article with both asciidoctor@3.0.4 and asciidoctor@4.0.2 and diffing — no difference), so the generated site content is unchanged. This keeps the Dependabot v4 bump in place rather than reverting it.

Verification

  • asciidoctor@4.0.2 resolves the { convert } import and converts on Node 18 (the workflow's runtime).
  • Diff of v3 vs v4 conversion output: identical.
  • node --check passes on the edited script.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H1niVBoyczk8mXe9L7Fnzv

asciidoctor 4.x removed the default export and the factory-function API:
the old `import asciidoctor from 'asciidoctor'` + `asciidoctor().convert()`
now throws "does not provide an export named 'default'" at module load, so
every Publish to website run has failed since the v4 bump landed.

Switch to the v4 named `convert` export and await its two call sites (both
already inside async callbacks). v4's convert produces byte-for-byte
identical HTML to v3 on the learning-path articles, so published output is
unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H1niVBoyczk8mXe9L7Fnzv
@rrrutledge
rrrutledge marked this pull request as ready for review September 8, 2026 15:47
@rrrutledge
rrrutledge requested a review from a team as a code owner September 8, 2026 15:47
@rrrutledge
rrrutledge merged commit f83e613 into main Sep 8, 2026
4 checks passed
@rrrutledge
rrrutledge deleted the fix-asciidoctor-v4-esm-import branch September 8, 2026 15:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant