Upgrading

Bring a site that sitekit init made up to the version of the kit you have installed, without losing what you changed.

Why it exists

init copies the template into your repository, and from then on the files are yours. When the kit fixes something, such as a contrast value, a security finding in a helper or a new theme, you would have to copy files by hand and guess which ones changed. sitekit upgrade does that comparison for you.

It can do it safely because init and add write a lock file, site/.sitekit.json. The lock holds the version that wrote the files and a hash of every file as it was written. For each file in the lock, the upgrade compares three things: your file now, the version it was written from (by its hash), and the kit’s file.

Run it

Run it from the root of the repository, with the newest kit:

npx docs-sitekit@latest upgrade

Use --dir <folder> when the site is not in site/. The command prints what it did to every file and what to do next. It exits with 0 when the upgrade ran, also when files are left for you to merge.

The four cases

A file that is the same in both versions, and a file you already copied from the new version by hand, need nothing and are counted as current. A file you deleted is not brought back. A file in the lock that the kit no longer ships is left where it is and listed.

If you already have a file at the path of a new file of the kit, and it is not the same, the upgrade treats it as the third case: your file stays and the kit’s version is written as .sitekit-new.

Look before you write

--dry-run prints the same report and writes nothing, not even a .sitekit-new file:

npx docs-sitekit@latest upgrade --dry-run

The upgrade is also a dry run by default when git status shows uncommitted changes in the repository, and it says so. Commit or stash first, so that a single git diff shows what the upgrade did. Pass --apply to write anyway. When git is not available, or the folder is not a repository, the upgrade cannot tell and writes.

Merge a conflict

For a file with a .sitekit-new copy, compare the two, bring what you want into your file, and delete the copy:

diff site/src/styles/prose.css site/src/styles/prose.css.sitekit-new

Your file is never overwritten in this case, so nothing is lost if you leave it for later. The lock keeps the old hash of that file, so the next upgrade finds the same conflict until your file is the new version.

A file the kit renamed

From 0.3.0 every file of the kit has a lowercase kebab-case name: SiteHeader.astro is site-header.astro, and buildDocuments.ts is build-documents.ts. The upgrade finds the old name in the lock and moves the file for you:

• A file you did not edit is deleted under the old name, and the new version is written under the new one. The report lists it with an arrow, site/src/…/SiteHeader.astro → site/src/…/site-header.astro.
• A file you edited is moved to the new name with your changes, and the kit’s version is next to it as .sitekit-new, as in any other conflict. The lock keeps the hash of the version you started from, so the next upgrade still sees your edits.
• A file you deleted is not brought back under the new name.

Imports inside the template now go through @/, which is the src/ folder of the site, so import { loadSite } from "../../infrastructure" is import { loadSite } from "@/infrastructure". A file of your own that imports a renamed file by its old name needs the new name. The build says which file and which import.

What it never touches

• Your content. docs/, examples/, README.md and CHANGELOG.md are not in the lock.
• Files that are not in the lock and that the kit does not ship. Your own files in site/ stay as they are.
• The deploy workflow, .github/workflows/docs.yml. When it still pins the old version, the report says so and you change it.
• sitekit.config.json, with one exception: an option that did not exist in your version is added with the value that keeps the site as it was. Nothing you have set is changed.

The options added this way are theme with default: "dark", search, llms, editLink and lastUpdated with enabled: false. The site looks and works as before, and you turn a feature on when you want it. A key is not written when the site already has the files of that feature.

package.json and package-lock.json are compared like any other file, with the name and description your site already has, so the name is not a change. If the kit changed the dependencies and you did not edit those files, they are replaced and you run npm install in the site folder.

After the upgrade

The lock is rewritten with the version that ran the upgrade, and with the new hash of every file that was replaced or added. A file that was kept or left for you to merge keeps its old hash.

1. Run npm install in the site folder when package.json changed.
2. Build the site and run npx docs-sitekit check.
3. Merge the .sitekit-new files, if any, and delete them.
4. Set the version of .github/workflows/docs.yml to the one you upgraded to.