Skip to content

Get started: fix npm-based flows for 0.17 Dart Sass, de-dupe prerequisites - #2749

Merged
chalin merged 25 commits into
google:mainfrom
chalin:chalin-m24-get-started-017-fixes-2026-0827
Aug 28, 2026
Merged

Get started: fix npm-based flows for 0.17 Dart Sass, de-dupe prerequisites#2749
chalin merged 25 commits into
google:mainfrom
chalin:chalin-m24-get-started-017-fixes-2026-0827

Conversation

@chalin

@chalin chalin commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator
  • Setup-flow correctness for 0.17: every npm-based get-started and migration flow now installs Dart Sass and runs Hugo through npm scripts, the failure mode a new troubleshooting entry diagnoses (including its warm-cache false-success trap); flow prose, prerequisites, and the docsy-example README now agree. Also corrects the migration guide's invalid hugoVersion.min TOML/JSON and its macOS-failing sed -i.
  • Prerequisite ownership: the shared prerequisites page routes its sections by setup option and owns the tool requirements (Windows Bash, Go floor per Hugo); other-options and the setup guides defer to it; restating openings, descriptions, and stale claims trimmed section-wide.
  • Publication gate: npm run install:safe lands in docsy-example with the 0.17 wave; publish with the 0.17 deploy/prod fast-forward, not before.
  • Preview(s):

- 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 chalin added this to the 0.17.0 milestone Aug 27, 2026
@chalin
chalin marked this pull request as ready for review August 27, 2026 19:41
chalin added 14 commits August 27, 2026 15:45
- 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
- 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
@chalin chalin changed the title Get started: align example-site flows with 0.17-era install scripts Get started: fix npm-based flows for 0.17 Dart Sass, de-dupe prerequisites Aug 27, 2026
chalin added 6 commits August 27, 2026 17:22
- 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
- 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
@chalin

chalin commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator Author

Validation notes for the migration-guide changes (the smoke matrix doesn't exercise this flow):

  • The portable sed '/theme = \["docsy/d' config.toml > hugo.toml && rm config.toml replacement was executed on macOS (BSD sed) against a sample config.toml: theme line removed, other lines preserved. The previous sed -i form errors on BSD sed.
  • The appended npm commands (sass-embedded pinned install, npm pkg set scripts.hugo=hugo, npm run hugo -- server) are byte-identical to the from-scratch flow's, which the smoke matrix covers on Ubuntu and Windows.
  • The Windows tab's findstr line is unchanged; only the same smoke-covered npm commands were appended.
  • hugoVersion.min quoting matches the from-scratch page's proven examples of the same shortcode.

chalin added 2 commits August 27, 2026 19:34
- 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
@chalin

chalin commented Aug 27, 2026

Copy link
Copy Markdown
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 config.toml site and a site already on hugo.toml. Both: theme line removed, config intact, npm run hugo builds cleanly with zero warnings (the step order keeps hugo mod npm pack as the last package.json writer, which is what prevents Hugo's dependencies-out-of-sync warning). The Windows tab is trace-reviewed only.

@chalin
chalin merged commit 7b6e49f into google:main Aug 28, 2026
18 checks passed
@chalin
chalin deleted the chalin-m24-get-started-017-fixes-2026-0827 branch August 28, 2026 00:00
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