Skip to content
GDDKit GDDKit Docs

Files, assets & backups

GDDKit is local-file software. Knowing which data lives inside the project and which data lives beside it prevents most broken-image, missing-logo, and sync-conflict problems.

What is inside .gddkit

The project file is formatted, human-readable JSON. It stores:

  • project ID, title, tagline, author or studio, genres, platforms, logo path, version, and timestamps;
  • each section’s Markdown content and last-modified timestamp;
  • custom section definitions and the visible section order;
  • changelog versions, dates, summaries, and bullet entries.

The file is not a ZIP or asset package. Images inserted into section content remain separate files, and the project logo remains a referenced path.

My Game Design/
├── My Game Design.gddkit
├── images/
│   ├── combat-loop.png
│   └── clipboard_20260715_142233123.png
└── project-logo.png

Images inserted with the toolbar or pasted from the clipboard use paths such as images/combat-loop.png, resolved relative to the .gddkit file’s directory. GDDKit creates the images/ folder automatically and avoids overwrites with suffixes such as _1 and _2.

The project-logo picker stores the selected filesystem path. It does not copy or embed the logo. Keeping the source logo in the project directory is still useful, but after moving the directory you may need to reselect it under Tools → Edit Project Details….

How saving works

On manual or automatic save, GDDKit:

  1. serializes the current project to <project>.gddkit.backup;
  2. removes the previous main file when it exists;
  3. moves the completed temporary file into the .gddkit path;
  4. updates the recent-project list.

After a successful save, the temporary .backup has become the main file and normally no longer exists.

Recover from a leftover .backup

If a save was interrupted or the main file is corrupted, GDDKit reports whether a sibling .gddkit.backup exists. Recovery is manual:

  1. Close GDDKit.
  2. Copy both the damaged .gddkit and .gddkit.backup elsewhere before changing either one.
  3. Duplicate the .backup copy and rename that duplicate to end in .gddkit.
  4. Open the duplicate with File → Open Project….
  5. Inspect sections and export a test document before replacing any primary file.

If no .backup exists, restore from your own history. Do not delete the damaged file; it can still help diagnose the problem.

Back up global preferences

Workspace settings, recent paths, saved section presets, custom PDF styles, and imported PDF fonts are global rather than project-local. They live in the operating system’s local application-data GDDKit folder:

  • settings.json
  • recent_projects.json
  • Fonts/

On Windows, the folder is %LOCALAPPDATA%\GDDKit. Linux and macOS locations follow the runtime’s local application-data directory and can vary, so avoid relying on a hard-coded path there.

Copy this folder while GDDKit is closed if you need to migrate reusable presets, styles, and fonts to another installation.

Use Git without conflicts

.gddkit JSON and project-relative images work well with version control when one person owns edits to the document at a time.

  1. Commit the .gddkit file and images/ together.
  2. Commit before and after a substantial writing session.
  3. Pull before opening GDDKit and close it before switching branches.
  4. Do not let two people save the same file concurrently; v2 has no file lock, merge interface, presence, or conflict detector.
  5. Review JSON conflicts carefully. A syntactically valid merge can still lose a section-order entry or changelog item.

The same rule applies to Dropbox, OneDrive, Google Drive, NAS folders, and other synchronizers: one active editor per project file. A “conflicted copy” is not something GDDKit merges automatically.

Privacy and network boundaries

Normal project editing, local image preview, Mermaid rendering, save, and local export do not require a GDDKit account. Network access is used when you:

  • check for application updates;
  • submit a bug report or feature request;
  • include an HTTP(S) image that the PDF exporter must download;
  • open a web link from the preview or documentation menu.

Feedback can include a screenshot of the application. Review it for confidential design content, file paths, email addresses, or internal names before submission.

Move a project to another computer

  1. Save and close GDDKit.
  2. Copy the complete project directory, including images/.
  3. Install GDDKit on the destination computer.
  4. Open the copied .gddkit file.
  5. Reselect the project logo if its old absolute path no longer exists.
  6. Inspect image-heavy and Mermaid-heavy sections in Split mode.
  7. Export a test PDF to verify fonts, remote images, and theme availability.

Custom PDF themes, saved section presets, and imported fonts do not travel inside the project. Copy global preferences separately or recreate them on the destination computer.