{"schemaVersion":1,"title":"Upgrade a customized site","url":"https://appgram.github.io/docsy/guides/reference/upgrading","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/reference/upgrading","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/reference/upgrading.json","version":"current","locale":"en","markdown":"# Upgrade a customized site\n\nRecord template provenance and compare upstream fixes without overwriting your source or content.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nGenerated Docsy sites own their Astro source. That means `npm update` does not merge new Docsy components into a customized project.\n\n## Record the baseline\n\nNew projects include `.docsy/template.json`: generator version, deployment selection, and SHA-256 hashes of the initial framework files. Commit this file. YAML, authored content and your package settings remain yours; the manifest is not an automatic updater.\n\n## Compare a new template safely\n\nGenerate a separate, untouched project from the desired Docsy package. Use the same deployment options as your current site. From your existing site, run:\n\n```bash\nnpm run docsy -- upgrade --from ../fresh-docsy\n```\n\nThis writes a local report under `.docsy/upgrades/`, never overwriting, deleting or installing project files. It distinguishes upstream changes, local-only changes, conflicts and proposed removals. The candidate must match its own generation manifest; a customized candidate is rejected.\n\nReview the report and compare files with the clean project. Merge only the changes you want on a branch. Review dependency and workflow changes separately; preserve your content, branding and access settings. Run validation, the build, your own example tests and a rendered preview before merging. Keep the old baseline until all relevant changes have been reviewed; never replace it merely to hide conflicts.\n\n## Older generated sites\n\nDo not invent hashes for an unknown baseline. Recover the exact generator release or commit originally used and generate a clean project from it. Review differences with your existing site before adopting provenance. If the original release is unavailable, use a manual source comparison and record that the baseline is unknown. The comparison command refuses to guess.\n\n## Release candidates and published versions\n\nUse a specific registry version such as `@appgram/docsy@0.4.2` to generate a clean upgrade baseline. `npm run release:pack` creates a local tarball for testing unreleased changes; it does not publish to a registry. Only versions actually listed in npm are registry releases. Publication requires the separate manual release workflow, owner-controlled gate and explicit confirmation. Generated documentation projects stay private npm packages by default.\n\n","contentLocale":"en","isFallback":false,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/reference/upgrading.md"}