Get started: fix npm-based flows for 0.17 Dart Sass, de-dupe prerequisites - #2749
Merged
chalin merged 25 commits intoAug 28, 2026
Merged
Conversation
- Switches example-site-as-template TL;DR and Preview flows to `npm run install:safe` + `npm run serve`, matching the docsy-example README - Adds a "Missing Dart Sass compiler" troubleshooting entry, with a warm-transform-cache caveat - Fixes the minimum Go version in the prerequisites
chalin
marked this pull request as ready for review
August 27, 2026 19:41
- Aligns the Preview intro prose with the npm-run fence (was still "use hugo's `server` command") - Matches the Dart Sass error excerpt's punctuation to Hugo's actual message
- Notes the Windows Bash requirement for the example site's npm scripts - Generalizes the cache-clearing advice to the configured resourceDir
- Sources the Go minimum from Hugo's module requirements (1.18), not docsy.work - Defers the Dart Sass remedy to its Install Dart Sass home; trims the error excerpt to the sibling entry's shape - Tightens the live-preview sentence
…ted-017-fixes-2026-0827
- Ends the from-scratch and other-options preview steps' bare `hugo server`, the no-sass failure the example-site flow was already cured of - Folds the Dart Sass compiler install into the from-scratch dependency step
- Single-homes the example-site-first recommendation on the section index - Recasts descriptions that restated their titles; cuts openings that restated descriptions - Reduces the Go and Git prerequisites to requirement, check, and download link
- Replaces the copied Hugo and Node install procedures with requirement summaries linking to the shared page, which absorbs the nvm tip - Preserves the hugo-extended-npm anchor and repoints its inbound links to the section's new home
- Tells example-site users up front which prerequisite sections apply: install:safe supplies pinned Hugo and Dart Sass tools - Notes, numberlessly, that projects can enforce their own Node/npm floors at install time
- Re-homes the Windows Bash requirement in the shared prerequisites; the TL;DR keeps a pointer, placed before its commands - Routes troubleshooting's install recovery per setup (the example-site and npm-package cases diverged); trims the error excerpt to its searchable signature - Corrects submodule-prepare semantics, go.mod/go.sum attribution, and a Hugo version tip long obsolete - Defers Hugo install mechanics to Hugo's docs; widens the prerequisites description to the page's shared role; trims remaining restatements
…ted-017-fixes-2026-0827
- Drops the ineffective tag-selection step: GitHub templates copy only the default branch; states the semantics and routes release-pinned starts to the clone option - Pins the npm-package option's sass-embedded to the tested version - Corrects the hugo mod npm pack layout description in its three homes: the command generates a workspace, it no longer edits the root manifest - De-dupes the config-recovery paragraph to Basic site configuration; cuts remaining padding and non-action notes
- Adds the compiler install and npm-run Hugo invocation to both TL;DR tabs and the dependency step - Quotes hugoVersion.min in the TOML and JSON examples, which were invalid syntax - Replaces the in-place sed, which fails on BSD/macOS, with a portable redirect - Reassigns go.sum to dependency resolution, drops the obsolete 0.110 tip, and compacts the graph-check and cleanup steps
Collaborator
Author
|
Validation notes for the migration-guide changes (the smoke matrix doesn't exercise this flow):
|
- Guards the migration config rename: the round-8 redirect form truncated an existing hugo.toml when config.toml was absent; the portable sed -i.bak form now edits hugo.toml in place (both tabs; detailed path gains the rename sentence) - Reorders every flow so hugo mod npm pack is the last package.json writer; otherwise each later build warns that npm dependencies are out of sync (verified on fresh sites) - Defines the hugo npm script in the npm-package option, which only deferred to the prerequisites
…ted-017-fixes-2026-0827
Collaborator
Author
|
Follow-up validation: the migration guide's final Unix TL;DR was executed end-to-end (macOS, hugo-extended 0.164.0, docsy/theme@v0.16.0) on both entry states: a legacy |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
hugoVersion.minTOML/JSON and its macOS-failingsed -i.npm run install:safelands in docsy-example with the 0.17 wave; publish with the 0.17deploy/prodfast-forward, not before.