Guide · Astro

Install an Astro theme

Q: npm install or npm run build fails with a note about the Node version.

Astro 7 needs Node.js 22.12 or later. node -v shows your version. Update, then delete node_modules and run npm install again.

Q: Sitemap and canonical links point to example.invalid.

The domain is missing. Set it in astro.config.mjs under site, or export with --site-url. Then build again.

Q: CSS, images or fonts are missing on the server.

The paths start with /assets/ and assume the domain root. If the site sits in a subfolder, they do not match. Upload dist/ to the root folder or use a subdomain of its own.

Q: An embedded video, map or form service is blocked.

public/_headers and public/.htaccess set a strict content security policy: only content from your own domain. Add the service there on purpose (frame-src, form-action, script-src) and update the privacy policy.

Q: The export stops with “export refused”.

kk checks the design before exporting and names every error with file and line, for example a section without a name. That happens when you changed the HTML pages in the package first. Fix the named spot, or export from the untouched package and change things afterwards. Also check your Node version with node -v: below 22 the tool does not run.

The design package becomes an Astro project. Every section is a component, the copy sits next to it as JSON. npm run build turns it into a static website.

In the example the design is Fieldnote (free, short name fieldnote). For your design, use its short name.

What you need

Node.js 22.12 or later (stated in package.json).
Git, for the Kiekkist tool.
A web space or host for static files.

What is in the export

Folder fieldnote-astro/

package.json: Astro 7 and @astrojs/sitemap, scripts dev, build, preview.
astro.config.mjs: Domain (site), trailing slash on every address, sitemap.
src/pages/: One .astro file per page.
src/components/: One component per section. Headers exist per page because of the marked menu item.
src/content/: Copy: sections/<section>.json per section, lists as <list>.json.
src/layouts/Base.astro: Base layout with title, description, canonical and Open Graph.
public/: tokens.css, assets/ with CSS, fonts and images, plus .htaccess and _headers with security headers.
AGENTS.md: Rules for AI assistants: tokens only, no third-party servers, keep the legal pages linked.
DESIGN.md, EXPORT.md: Design rules and export report.

By hand

Download the ready export

Free designs download from the design page, purchased ones from the download page with your licence key. Then choose what to load: Astro project, everything in one ZIP, or the design package only. Unpacked, the export sits in fieldnote/exports/astro/, with INSTALL.md and EXPORT.md. It is the same content as fieldnote-astro/ in the steps below.
Or create it yourself

To rebuild the export from a changed design package, use the Kiekkist tool kk. It is open source, runs locally and needs Node.js 22 or later. Put it next to the design folder (in the “design package only” download it is fieldnote/). The command writes fieldnote-astro/; --no-check skips the visual comparison (for it, run npx playwright install chromium once).
```
git clone https://github.com/tillheidrich/kiekkist
cd kiekkist && npm ci && cd ..
node kiekkist/cli/kk.js export ./fieldnote --target astro --site-url https://www.your-domain.com --no-check
```
Install and start

--site-url writes your domain into astro.config.mjs, for the sitemap and canonical links. Without it there is a placeholder you change later.
```
cd fieldnote-astro
npm install
npm run dev
```
Look at it in the browser

The site runs at http://localhost:4321/. Changes to files show up right away.
Build

The command writes the finished website to dist/: HTML, CSS, fonts, images, sitemap-index.xml. npm run preview shows the built version first.
```
npm run build
```
Publish

Upload the contents of dist/ to the root folder of your web space, by SFTP or FTP. Include hidden files: on Apache hosts .htaccess sets the HTTPS redirect and security headers. On hosts with Git deployment, set npm run build as the build command and dist as the output folder. No Node server is needed.

With an AI assistant

Your AI coding assistant can create the export, replace the sample content and tell you what is left for you to do. Give it the unpacked design folder and have it read these files:

fieldnote/DESIGN.md: design rules, colours, fonts, what not to change
fieldnote/tokens.json and tokens.css: every colour, type and spacing value
fieldnote/README.md: what is in the package and what to replace before launch
fieldnote/LICENSE.md: what you may do with code, copy and photos
fieldnote/UEBERGABE/: handover templates for your client (German and English)
in the export fieldnote-astro/AGENTS.md and EXPORT.md

Prompt to copy. Replace the details in square brackets. Instead of fieldnote, use your design’s short name.

The folder ./fieldnote holds a website design as a package. Build an Astro website from it for [company name], domain [www.domain.com].
1. Read fieldnote/DESIGN.md, README.md and LICENSE.md first. Do not change the design; use only values from the tokens.
2. Get the Kiekkist tool (git clone https://github.com/tillheidrich/kiekkist, then npm ci inside it) and create the export: node kiekkist/cli/kk.js export ./fieldnote --target astro --site-url https://[www.domain.com] --no-check. Then read fieldnote-astro/AGENTS.md and EXPORT.md and follow the rules there.
3. Replace all sample content in src/content with my details: [name, address, services, copy]. Change copy only in src/content, not in the components.
4. Fill in the placeholders on the legal pages with my details; ask me for anything you do not know.
5. npm install, npm run build. Fix errors until the build passes, and show me what you changed.

Have every change shown to you before it goes onto the live site. Passwords and licence keys do not belong in the chat or in the repository.

Replace content, images and logo

Copy: in src/content/sections/<section>.json. Lists such as projects, team or prices have their own files in src/content/. Page title and description are at the top of each file in src/pages/.

Images: in public/assets/img/. The paths are in the JSON files (imgSrc, imgSrcset) or directly in the page. Either save the new image under the same name and in the same sizes, or change the paths in the JSON file. Update the alt text (imgAlt) as well.

Logo: an SVG in the header. It is in src/components/SiteHeader.astro and in the per-page headers (*SiteHeader.astro). Change all of them.

Adapt colours and fonts

Every colour, font and spacing value is a CSS variable in public/tokens.css, for example --c-paper or --font-sans. Change the value and you are done: the rest of the CSS only reads these variables.

For bigger changes: change the values in tokens.json in the design package and export again. Note that this only overwrites the export folder with --force; save your content from src/content/ first.

Different font: put the woff2 into public/assets/fonts/, add an @font-face to fonts.css, switch --font-… in tokens.css. Do not load fonts from third-party servers.

Colours are given in OKLCH. After every change, check text against background contrast (at least 4.5:1).

What the licence allows

Purchased design: you may build unlimited websites with it, your own and your clients’, and hand them over with all rights. Your client may keep running the site without you. What is not allowed: passing on or selling the design itself, also not as a template, theme or kit. The full text is in the licence.

Free design: LICENSE.md in the package applies. For Fieldnote that is CC BY 4.0: use for clients and commercial work is fine, with a short credit in the source or on a credits page.

Photos from the package may only be used as part of the website you build with it. Do not pass them on separately or use them as stock.

Fonts are under the SIL Open Font License. Keep the licence files LICENSE-*.txt next to the font files.

Never put your licence key into a repository or theme files. KIEKKIST-LICENCE.txt in the package only names the licence ID and project.

Common problems

npm install or npm run build fails with a note about the Node version.

Astro 7 needs Node.js 22.12 or later. node -v shows your version. Update, then delete node_modules and run npm install again.

Sitemap and canonical links point to example.invalid.

The domain is missing. Set it in astro.config.mjs under site, or export with --site-url. Then build again.

CSS, images or fonts are missing on the server.

The paths start with /assets/ and assume the domain root. If the site sits in a subfolder, they do not match. Upload dist/ to the root folder or use a subdomain of its own.

An embedded video, map or form service is blocked.

public/_headers and public/.htaccess set a strict content security policy: only content from your own domain. Add the service there on purpose (frame-src, form-action, script-src) and update the privacy policy.

The form sends nothing.

That is on purpose: in the package it is a demo without a recipient. Set your form endpoint as the action and switch to method="post".

The export stops with “export refused”.

kk checks the design before exporting and names every error with file and line, for example a section without a name. That happens when you changed the HTML pages in the package first. Fix the named spot, or export from the untouched package and change things afterwards. Also check your Node version with node -v: below 22 the tool does not run.

What we checked

Checked with two designs (Fieldnote and Kestrel Row): export created, npm install and npm run build with Astro 7.4 and Node 22 without errors, every page built.

More about this export All guides See the gallery

Other exports: WordPress, HTML, React, Elementor

What you need

What is in the export

By hand

Download the ready export

Or create it yourself

Install and start

Look at it in the browser

Build