Common issues and their solutions when working with Harold.
Symptoms:
Error: Cannot find module 'harold-scripts'
Solution:
npm installharold-scripts is in your package.jsonnode_modules and package-lock.json, then run npm install againSymptoms:
Missing Front Matter keys for example.md. Required keys are: layout, title, publicationDate. File was not generated!
Solution: Ensure all markdown files have required front matter fields:
---
layout: 'blog-post'
title: 'My Post Title'
publicationDate: '2025-12-20'
---
All three fields are required for every markdown file.
Symptoms:
No posts directory found. Skipping posts generation.
Solution: This is normal if you don't have a posts directory. Since v1.3.0, directories are optional. To fix:
src/posts/ directory if you want blog postsSymptoms:
Could not determine dimensions for image: image.jpg
Solution:
<img src="https://example.com/image.jpg" width="800" height="600" alt="Image" />
Symptoms:
Error: listen EADDRINUSE: address already in use :::3000
Solution:
PORT=3001 npm start# Find process using port 3000
lsof -i :3000
# Kill it
kill -9 <PID>
Symptoms: File changes don't appear when refreshing browser.
Solution:
build/ folder and rebuildnpm start)Symptoms: CSS loads on refresh but not on initial load.
Solution: This was fixed in v1.3.0. Update harold-scripts:
npm install harold-scripts@latest
Symptoms: SCSS changes saved but not visible in browser.
Solution:
_ prefix and are importedbuild/styles/ and restart dev serverSymptoms: Site looks fine locally but broken when deployed.
Solution:
relativePath helper for all asset paths.haroldrc:{
"hostDirName": "my-subdirectory"
}
npm run build and serve the build/ folderSymptoms: Images show broken icon or 404 in Network tab.
Solution:
src/assets/images//assets/images/photo.jpg (not ../images/photo.jpg)Photo.jpg ≠ photo.jpg)build/assets/images/Symptoms: Page content jumps when images load.
Solution: For v1.3.0+:
<img src="https://example.com/image.jpg" width="800" height="600" alt="Image" />
Symptoms: Internal links return 404 when site is in subdirectory (e.g., example.com/blog/).
Solution:
.haroldrc:{
"hostDirName": "blog"
}
relativePath helper for all links:<a href="{{relativePath 'about.html'}}">About</a>
<img src="{{relativePath 'assets/images/photo.jpg'}}" />
Symptoms: Paths starting with / don't work.
Solution:
.hbs files: Use relativePath helper.scss files: Use relative paths or configure hostDirNameSymptoms: Changes to .haroldrc not taking effect.
Solution:
.haroldrc in project root or src/ directory.haroldrc (not .haroldrc.txt)Symptoms: Changed mdFilesDirName but URLs still use /posts/.
Solution:
"docs", rename src/posts/ to src/docs/mdFilesLayoutsDirName to matchharold-search.jsbuild/ and run npm run buildSymptoms: Build takes minutes instead of seconds.
Solution:
Symptoms: Page takes long to load in browser.
Solution:
{
"minifyCss": true,
"minifyHtml": true
}
Symptoms: HTML tags appear as text instead of rendering.
Solution: Harold supports raw HTML in markdown by default. If not working:
< and > aren't escapedSymptoms: Markdown like **bold** or # Heading not rendering.
Solution:
.md or .markdown--- delimitersSymptoms: npm run build works locally but fails on Netlify/Vercel/GitHub Actions.
Solution:
{
"engines": {
"node": ">=20.0.0"
}
}
harold-scripts buildharold-scripts is in dependencies not devDependenciesSymptoms: Pages work locally but return 404 when deployed.
Solution:
build/ (or your configured outputDirName)If you're still stuck:
npm list harold-scripts)node --version)Add to your package.json:
{
"scripts": {
"start": "DEBUG=* harold-scripts start",
"build": "DEBUG=* harold-scripts build"
}
}
Create a minimal test case:
src/pages/index.hbssrc/styles/main.scssInspect build/ directory: