Kiekkist
Menu
DE

Guide · WordPress

Install a WordPress block theme

The design package becomes a block theme with theme.json, templates and patterns. You upload it like any theme. No plugins needed.

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

What you need

What is in the export

Folder fieldnote-wordpress/

fieldnote.zip
The theme as a ZIP (in the download: fieldnote-wordpress-theme.zip). This is the file you upload to WordPress. Beta: menu and texts are edited in the Site Editor.
fieldnote/
The same theme folder unpacked, for FTP or for edits before uploading.
fieldnote/theme.json
Colours, fonts, spacing and the list of page templates.
fieldnote/templates/
front-page.html for the home page, page-<name>.html for every other page, 404.html.
fieldnote/parts/
Header and footer. There is one variant per page because the current menu item is marked.
fieldnote/patterns/
One pattern per section, also insertable on its own in the editor.
fieldnote/assets/
CSS, fonts (woff2), images and a small script.
EXPORT.md
Sections, pages, notes about the export.
blueprint.json
Optional, for a preview in WordPress Playground.

By hand

  1. 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: WordPress theme (ZIP, beta), everything in one ZIP, or the design package only. You get fieldnote-wordpress-theme.zip directly, the theme ready to upload. In the folder fieldnote-wordpress/ below it is called fieldnote.zip.

  2. 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-wordpress/; --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 wordpress --no-check

  3. Upload the theme

    In WordPress: Appearance → Themes → Add New Theme → Upload Theme. Choose fieldnote-wordpress-theme.zip (self-made: fieldnote-wordpress/fieldnote.zip), click “Install Now”, then “Activate”. Do not upload the “everything” ZIP or the design package: they are not themes, and WordPress then reports that style.css is missing. Beta: menu and texts are edited in the Site Editor.

  4. Set permalinks

    Settings → Permalinks, choose “Post name”, save. The menu links point to addresses like /projects/. With “Plain” (?page_id=12) they lead nowhere.

  5. Create the pages

    For every template in templates/page-<name>.html create a page whose slug is exactly <name>. For Fieldnote: projects, coopers-yard, studio, contact, thanks, legal, accessibility, sitemap. WordPress then picks the matching template on its own. The template is also listed under “Template” in the page editor sidebar. You do not need a page for 404. The home page comes from front-page.html; nothing to set.

    • The content area of the new pages stays empty. The copy lives in the template.

  6. Change the copy

    Appearance → Editor → Templates, open the template (named like the page), click the text, change it, save. Sections are locked against restructuring: text and images can change, layout and colours cannot. That keeps the site the way it was checked. Some parts, such as navigation, forms, disclosure widgets and images with several sizes, are HTML blocks. Edit those with “Edit HTML”.

  7. Change the menu

    Block themes have no Appearance → Menus screen. The navigation sits in the header parts. Because every page has its own header part (parts/header.html, header-projects.html and so on), the easiest way to change menu items is before uploading: search and replace across all files in parts/, then zip fieldnote/ again. After uploading, use Appearance → Editor → Patterns → Template Parts and edit each header.

  8. Fill in the legal pages

    The templates legal (legal notice and privacy) and accessibility (accessibility statement) have placeholders like [Fill in: …]. Fill them in in the editor. German designs also bring UEBERGABE/rechtstexte/ with Impressum, Datenschutz and Barrierefreiheit as HTML skeletons. They are templates, not legal advice.

  9. Fonts and plugins

    The fonts ship with the theme and are loaded through theme.json. Nothing to install, nothing loaded from Google. You only need a plugin for the form: out of the box it sends nothing, it only forwards to the thank-you page. Use a form plugin or form service you trust and update the privacy policy.

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)
  • after the export fieldnote-wordpress/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. Turn it into a WordPress block theme for [company name]. 1. Read fieldnote/DESIGN.md, README.md and LICENSE.md first. Do not change the design; use only values from tokens.json. 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 wordpress --no-check. Then read fieldnote-wordpress/EXPORT.md. 3. Replace all sample content in fieldnote-wordpress/fieldnote with my details: [name, address, phone, services]. Change menu items the same way in every file in parts/. 4. Check that image paths in patterns/*.php have a slash after the theme folder. If not, replace get_theme_file_uri( '/' ) with trailingslashit( get_theme_file_uri() ). 5. Check every PHP file with php -l and zip fieldnote-wordpress/fieldnote again as fieldnote.zip. 6. Give me the list of pages with their slugs that I need to create, and the placeholders on the legal pages I have to fill in myself. Do not work on my live site without asking first.

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 the Site Editor in the matching template, or before uploading directly in templates/, parts/ and patterns/. Every name, address, figure and project in the package is made up. README.md says what to replace before launch.

Images: they sit in assets/img/ and mostly appear in HTML blocks. The easiest way is to swap them before uploading: save the new image under the same file name and with the same dimensions, for every size and format (AVIF and WebP). If you want fewer sizes, change the srcset in the HTML block to one image from the media library. Always update the alt text too.

Logo: the logo is a small SVG with text in the header (class="brand"). Replace it in every file in parts/ so it matches on every page.

Adapt colours and fonts

The source of every colour and font is tokens.json in the design package. Cleanest way: change the values there, create the export again, upload the theme again and confirm that WordPress replaces the installed one. Copy you changed in the editor stays; it lives in the database.

Quick way for small changes: in theme.json under settings.color.palette, change the color value of a colour. The theme CSS reads the colours from there.

Different font: put the woff2 file into assets/fonts/ and adjust the entry in theme.json under settings.typography.fontFamilies (fontFace with file:./assets/fonts/…). Do not load fonts from Google’s servers.

Colours, fonts and spacing are locked for editors on purpose. New colours outside the palette are not available in the editor.

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

“The uploaded file exceeds the upload_max_filesize directive”

Theme ZIPs are a few megabytes because of images and fonts, 2.5 to 7.5 MB in our tests. Many hosts allow 2 MB. Two ways: raise upload_max_filesize and post_max_size in your host’s control panel. Or upload the unpacked folder fieldnote/ by SFTP or FTP into wp-content/themes/ and activate the theme under Appearance → Themes.

“The package could not be installed. The theme is missing the style.css stylesheet.”

You picked the wrong ZIP: either the Kiekkist download ZIP, or a ZIP where the theme folder sits inside another folder. Upload fieldnote-wordpress-theme.zip (or, self-made, fieldnote-wordpress/fieldnote.zip). If you zip it yourself, style.css has to sit directly in fieldnote/.

Images are missing; the alt text shows instead of the photo.

Check the image address in the page source. If it reads …/themes/fieldnoteassets/img/… without a slash, open patterns/*.php and replace get_theme_file_uri( '/' ) with trailingslashit( get_theme_file_uri() ). Then upload the theme again.

Menu links or subpages show “Page not found”.

Either permalinks are set to “Plain”, or the page slug differs from the template name. Slug and template name must match, so contact and page-contact.html. If WordPress lives in a subfolder, the menu links point to the domain root; adjust the links in the header parts.

Theme Check reports errors.

The Theme Check plugin reports a missing preview image (screenshot.png) and a missing “License URI”. Both only matter for the wordpress.org theme directory. They make no difference to your site.

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): theme ZIP installed and activated through “Appearance → Themes → Upload Theme” on a local WordPress test instance (WordPress 7.1, PHP 8.3), pages created and opened, templates opened in the Site Editor without block errors. Plus php -l on every PHP file and the Theme Check plugin.

More about this export All guides See the gallery

Other exports: Astro, HTML, React, Elementor