Step-by-step guide
PostCarry
Move supported Hugo blog posts into an editable Astro project. Review the conversion, compare the rendered articles, and download the source and built site together.
You maintain a bounded Hugo Markdown blog and want to move its supported articles into Astro with an inspectable conversion and editable output.
See it in use
Carry a small blog into Astro
A screenshot walkthrough with fictional practice data. Select a step to explore.
1. Start with
Carry a small blog into Astro
Harbor Notebook has four authored pages, a linked SVG and two withheld pages.
Sample files and contents
Four authored pages use YAML and TOML dates, a linked SVG figure, duplicate headings, a .html route, one alias, a draft and a future publication.
Practice files and guides are free. The complete app is included only where the product page says so.
2. In the app

Try it in three steps
- Load the blog and inspect original versus carried Markdown.
- Build and review the two published routes and alias.
- Download the Astro project and open the built site.
Show every click and setting
- Load Harbor Notebook and inspect the original and carried Markdown.
- Build and compare; use the selector to inspect both published articles and both kept-unpublished articles.
- Download the Astro project and open the built site. Confirm that draft and future pages remain outside dist.
3. The result
Inspect the result
The generated article keeps its gauge, caption and links. Draft and future pages remain outside the published site.

What to check in the practice result
Two published articles at /notes/tide/ and /notes/gear.html, an alias at /old-tide/, and a neutral index. The gauge SVG stays byte-identical; reading/reading-1 heading IDs, caption emphasis and credit, and date offsets are retained. The two unpublished pages stay outside dist. All four authored articles receive native comparison.
This fictional example is shown in the working interface and in the supplied result. Review the guide before using your own files.
See the workflow at a glance
Choose a short explanation, then follow the worked example below. Check the requirements and compatibility before using your own files.
Carry the articles, then inspect the generated site.
A small blog migration should be reviewed at the article level. PostCarry moves supported Hugo Markdown content into an editable Astro project and packages the source with the built site. The fictional Harbor Notebook exercise preserves two published routes, an alias, heading IDs and a linked SVG, while draft and future articles remain outside the public output. Linux x64 and Node.js 22.12 or newer are required. Unsupported constructs stop export; compare the rendered articles before adopting the generated project.
View the illustrated card

Before you start
- Linux x64 with Node.js 22.12+ and desktop Chrome. The accepted environment used Node 22.22.2 and Chrome 152.
- Extract the entire buyer ZIP and keep its bundled files together. The sample needs no account or dependency download.
- Use a trusted copy of your Hugo source and the documented capture template. Keep the original project untouched.
- Read the supported-content limits before capturing a real site. This tool does not convert a whole Hugo theme.
Your first result
Start the local workbench
In the extracted buyer folder run node start.mjs, then open the printed localhost address in Chrome. Choose Try Harbor Notebook. No network download is needed for this example.
Inspect the carried articles
Switch between Original and Carried Markdown. Check the article routes, aliases and transformation notes. A blocking finding identifies the source file and line; resolve it in your working source copy and capture again.
Build and compare
Choose Build & compare. Read the grouped Articles, Resources, Aliases and Route inventory results. In Inspect the rendered pages, choose an article and scroll the captured Hugo and built Astro panes independently. Harbor Notebook has two published and two kept-unpublished choices. Check the gauge, caption and headings. The previews show article content in a neutral layout; they do not reproduce your Hugo theme. A failed comparison keeps download unavailable.
Download and inspect the starter
Choose Download Astro project. The archive includes editable Markdown, exact original front matter, route and heading maps, the built dist folder, and migration-plan/proof files. Drafts and future content are retained outside the public output. The full archive can still contain private source material; review it before handing it to someone else.
Open the built result or rebuild
To view the exported site locally, run python3 -m http.server 8080 --directory dist in the starter folder and open localhost port 8080. To rebuild it independently, run npm ci once with network access, then npm run build. Stop the local server with Ctrl+C when finished.
Capture your own trusted copy
Follow the included manual to add its article/title/date capture wrapper to a working copy. Restore the bundled Hugo executable bit with chmod +x tools/hugo if necessary. Run the manual’s capture command with that source directory, a new output baseline path outside it, a deliberate publication clock and the bundled Hugo path. Capture checks that source bytes stay unchanged. Open the resulting baseline in PostCarry and repeat the review.
Save a baseline and return later
Save the baseline before closing the app. Successfully opening a replacement baseline clears the previous proof, so run Build & compare again before downloading. A rejected import leaves the previous project and its verified download unchanged. Correct the stated problem and open the new baseline again. Stop the workbench with Ctrl+C. Any later edits to the exported starter need a fresh check of their own.
A worked example
Harbor Notebook — original fictional blog
Input: Four authored pages use YAML and TOML dates, a linked SVG figure, duplicate headings, a .html route, one alias, a draft and a future publication.
- Load Harbor Notebook and inspect the original and carried Markdown.
- Build and compare; use the selector to inspect both published articles and both kept-unpublished articles.
- Download the Astro project and open the built site. Confirm that draft and future pages remain outside dist.
Expected result: Two published articles at /notes/tide/ and /notes/gear.html, an alias at /old-tide/, and a neutral index. The gauge SVG stays byte-identical; reading/reading-1 heading IDs, caption emphasis and credit, and date offsets are retained. The two unpublished pages stay outside dist. All four authored articles receive native comparison.
More application screens
Compare the article, then carry the working site
Actual PostCarry 1.0.1 and generated Astro screens in Chrome on Linux, using the fictional Harbor Notebook sample.
1. Inspect the rendered article

2. Read the grouped proof

3. Review the unpublished pages too

4. Find the source of a blocker

5. Open the working result

Troubleshooting
Node or the bundled Hugo will not start
Check that the host is Linux x64 and Node is at least 22.12. Use the complete extracted folder. The manual explains restoring the Hugo executable bit.
Capture cannot find an article, title or date
Apply the manual’s article[data-postcarry], title and time[datetime] wrapper to your trusted working copy and capture again.
A shortcode or metadata field is unsupported
Review what that content means before changing it. Correct the working source deliberately and create a fresh baseline; the app will not silently discard unknown constructs.
The build succeeds but the comparison fails
Read the differing article token or resource check. Correct the source or rendering variant and capture again. Export stays blocked while the comparison differs.
Importing a new baseline fails
The new baseline was not opened. Your previous project, proof and verified download remain unchanged. Correct or recapture the new baseline and open it again. A successfully opened replacement needs Build & compare before downloading.
An independently rebuilt starter differs after edits
The original proof covers the original generated project. Inspect your changed routes, content and assets and verify the new build before deploying it.
Compatibility & limits
- Linux x64 and Node.js 22.12+ are required. Tested with Node 22.22.2, Chrome 152, Hugo 0.167.0 and Astro 7.3.5. Other hosts and Hugo versions are unverified.
- Up to 500 Markdown pages, 5,000 source files and 250 MiB of source plus captured article HTML. Each recognized text or article HTML file is limited to 1 MiB, each binary asset to 20 MiB and each serialized baseline to 360 MiB.
- Supports single-language YAML/TOML pages and leaf bundles, documented metadata, and the documented figure/ref/relref/highlight shortcode options. Unknown fields or constructs stop export.
- Capture runs Hugo against a trusted working copy using the manual’s article, title and date template. The browser review does not execute imported templates or scripts.
- Includes a neutral article layout. Your theme, homepage design, navigation, taxonomy styling, RSS, comments, search, multilingual setup, modules and deployment are not migrated. Raw HTML, custom render hooks or shortcodes, branch bundles, reference-style links, footnotes and expiry scheduling are excluded.
- External links are retained but not visited; remote assets are not fetched. Imported SVG files are retained as originals and need your own review before deployment.
- Draft and future articles and their resources stay outside the built public site. The full baseline and editable handoff still contain private source metadata and unpublished material: inspect them before sharing.
- Verification describes one captured source and generated build. It is not a promise of universal compatibility, search ranking or accessibility compliance. After editing the exported project, the old proof no longer verifies your changes.
- The app and its sample run locally with bundled dependencies. Independently rebuilding an exported Astro project requires npm ci with network access once. No hosting or deployment service is included.
Need a hand?
Tell us the product, host application and version, what you tried, and the exact error. Contact support with a fictional example; keep private customer files and passwords out of your message.