Move from GDDKit v1 to v2

GDDKit v2 replaces the Windows WPF application with an Avalonia desktop application and adds Linux and macOS packages. Existing .gddkit files remain supported: there is no import wizard or one-way project conversion.

Before you upgrade

1. Close GDDKit v1.
2. Copy each .gddkit file and its nearby asset folders to a separate backup location.
3. On Windows, optionally copy %LOCALAPPDATA%\GDDKit\settings.json and recent_projects.json.
4. If a project uses a logo or images, confirm that those files still exist. A logo is stored as a path, not embedded in the project.
5. Keep the v1 installer or standalone executable until you have opened and exported a copy of a project in v2.

Do not test with your only copy

Format compatibility is designed to be preserved, but a real backup also protects you from disk, sync, or user error. Open the copied project first and create a PDF smoke test.

Upgrade an installed Windows v1.0.5 copy

Installed v1.0.5 builds use the same Windows update channel as v2. You can use the application’s update flow when the v2 release is available on that channel, or install the current v2 setup package over the existing installation.

The Windows migration preserves:

• the existing .gddkit project format;
• %LOCALAPPDATA%\GDDKit\settings.json;
• recent-project data;
• the GDDKit package identity and Windows update channel.

If you ran v1 without installing it, download and install the current v2 Setup EXE. Keep the old v1 executable until the copied project opens and exports successfully in v2.

Open a v1 project

1. Launch GDDKit v2.
2. Select Open Existing GDD File or press Ctrl + O.
3. Choose the copied .gddkit file.
4. Check the project title, genres, platforms, section order, logo, and changelog.
5. Open sections that contain Markdown images or Mermaid diagrams and inspect Split mode.
6. Save to the copied project and export both Markdown and PDF.

Missing v2 fields receive safe model defaults when the project is read. Legacy Font Awesome section icons are mapped to the bundled Phosphor icon set.

What changes in v2

Area	v2 behavior
Desktop UI	Rebuilt with Avalonia across Windows, macOS, and Linux.
Genres	Expanded catalog with multiple genre selection; older custom values remain readable.
Sections	More icon choices, improved drag reordering, reusable built-in and saved section presets.
Editor	Edit, Preview, and Split modes; synchronized scroll; expanded Markdown toolbar; cross-section search.
Images	File insertion and clipboard image paste into a project-relative images/ folder.
PDF	Eight built-in styles, improved Mermaid rendering, and a reusable custom PDF Theme Designer.
Support	In-app update checks and bug/feature feedback with an optional screenshot.

GDDKit 2.0.1 additionally focuses on cross-platform stability, including Mermaid PDF reliability on Linux and macOS, Nordic Frost export fixes, macOS title-bar layout, and the restored Ctrl + E mode shortcut.

If something looks wrong

• The logo is missing: open Tools → Edit Project Details… and select it again. The stored path may point to the old computer or folder.
• Section icons changed: v2 maps legacy icons to Phosphor equivalents; choose another icon from the section context menu if needed.
• Images are missing: move the project’s images/ folder alongside the .gddkit file without changing their relative structure.
• A PDF style changed: PDF selection is a global setting. Check Workspace Settings and the PDF Theme Designer.
• The file will not open: do not overwrite it. Follow the project recovery steps in Troubleshooting & FAQ.

Can you go back to v1?

The project format is intended to stay compatible, but v1 does not understand every v2 editing or settings feature. Treat rollback as an emergency path: work on a copy, avoid depending on v2-only icon or preset behavior, and keep v1 and v2 from editing the same project at the same time.