Skip to content
GDDKit GDDKit Docs

Troubleshooting & FAQ

Start with a copy of the affected project, note the exact status message, and test the smallest reproducible section. Do not overwrite your only copy while diagnosing corruption or a sync conflict.

The preview is blank on Linux

  1. Confirm the AppImage is executable: chmod +x GDDKit-linux-x64.AppImage.
  2. Install GTK 3 and WebKitGTK 4.1 for your distribution.
  3. Launch the AppImage from a terminal and inspect missing-library output.
  4. Open a new project and test plain Markdown before Mermaid or remote images.
  5. Update to GDDKit 2.0.1 or later in the 2.x line for cross-platform preview/export fixes.

Common package names are libgtk-3-0 and libwebkit2gtk-4.1-0 on Debian/Ubuntu, or gtk3 and webkit2gtk4.1 on Fedora.

The project file will not open

The path may be missing, the JSON may be malformed, or a save/sync operation may have been interrupted.

  1. Close GDDKit and pause any sync client.
  2. Copy the .gddkit file and any sibling .gddkit.backup to a safe folder.
  3. Try the main copy from File → Open Project… rather than a recent card.
  4. If a .backup exists, duplicate it, rename the duplicate to .gddkit, and try that copy.
  5. Restore a known revision from Git or backup if neither opens.

The leftover .backup is opportunistic recovery material, not a guaranteed or historical backup.

A recent project card disappeared

Recent Projects stores at most ten paths, but renders only files that still exist and can be parsed. A stale path can remain in the stored list and occupy a slot, so fewer than ten cards may be visible. A card disappearing does not itself delete the project file.

Locate the project in the filesystem and use Open Project…. Opening it successfully adds the current path. There is no per-entry cleanup control; newer successful opens eventually push the oldest stored paths out.

Images are missing after moving or exporting

  • Move .gddkit and images/ together.
  • Resolve relative paths from the .gddkit directory.
  • Remember that Markdown export does not copy assets.
  • Put image Markdown on its own paragraph for PDF.
  • Replace absolute paths with toolbar-inserted project-relative paths.
  • For remote PDF images, check network access, the 10-second timeout, and 8 MB limit.

The project logo disappeared

The logo is a referenced external path and is not copied into .gddkit. Open Tools → Edit Project Details…, browse to the image at its new location, and save.

Mermaid shows source or an error in PDF

  1. Use an exact mermaid fenced block.
  2. Verify syntax in Split mode.
  3. Reduce the diagram to two nodes and one edge.
  4. Update to 2.0.1 or later, especially on Linux/macOS.
  5. Confirm the embedded preview runtime works on the platform.

PDF intentionally falls back to readable source/error content when rendering fails, so one diagram should not necessarily cancel the whole export.

The wrong PDF style exported

PDF style selection is global, not per project.

  • Save as Custom creates a reusable copy; Update Style saves changes to the selected custom style.
  • Save & Set Active stores it and selects it for export.
  • Workspace Settings also selects the active style.

Activate the intended style, then export again.

Designer preview and exported PDF differ

The Designer uses a fixed visual specimen, not the current project’s real QuestPDF output. Export a stress-test project and inspect the cover, TOC, longest section title, table, code, quote, image, Mermaid, and changelog.

A custom font does not appear

  • Use a valid .ttf or .otf file.
  • Confirm GDDKit can write to its local application-data Fonts folder.
  • Some fonts have invalid or unsupported internal family metadata.
  • Reopen the Designer after import if necessary.
  • Import the font on every computer that must reproduce the custom theme.
  • Confirm your license permits the intended PDF distribution.

v2 has no custom-font removal UI. Back up settings before manually changing global font files.

Settings reset or do not save

GDDKit can fall back to defaults when settings.json is unreadable, and save failures may be silent.

  1. Close the application.
  2. Back up the local application-data GDDKit folder.
  3. Check folder permissions and security software.
  4. Rename a malformed settings.json copy and relaunch to generate defaults.
  5. Recreate settings selectively rather than copying the malformed file back.

Update check says installation is required

Confirm that you are running a published package rather than a development build or raw publish output. If update checking remains unavailable or asks for an installation, reinstall the current Setup EXE, PKG, or AppImage for your platform from the official download.

PDF export seems stuck

The progress window stays open until work completes. Remote images can each wait up to 10 seconds, and Mermaid rendering adds time.

  • Wait for the current operation.
  • Replace remote images with local assets.
  • Test a copy with complex diagrams reduced.
  • Export to a local writable directory.
  • Update to the latest 2.x release.

Team edits overwrite each other

Released v2 has no real-time collaboration, file locking, or merge interface. Two instances can open the same file and the later save can overwrite earlier work.

Use one active editor, commit before handoff, pull before opening, close before branch changes, and keep .gddkit plus images/ in the same revision.

Frequently asked questions

Does GDDKit upload my project?

Normal local editing and export do not require an account or upload the .gddkit file. Update checks, feedback submission, remote images, and opened web links use the network.

Can I import Markdown, Word, PDF, or Notion?

No general importer is released in v2. You can open .gddkit files and manually paste/restructure text.

Can I export DOCX or HTML?

No. Released export formats are PDF and Markdown.

Is there a CLI or headless exporter?

Not in the released v2 desktop product.

Does v2 include cloud or live collaboration?

No. The released build is local and single-user. Treat collaboration work on development branches as unreleased unless an official product release says otherwise.

Are screenshots and images embedded in .gddkit?

No. Section images live beside the project, normally in images/; the logo is an external path.

Is .backup a permanent backup?

No. It is a temporary save target that normally becomes the main file after a successful write.

The text is styled, but clickable annotations are not guaranteed. Include readable URLs where necessary.

Should I use Command shortcuts on macOS?

The v2 code binds the Control modifier. Use Control with the documented key unless a later version changes this.

Can I remove or restore a built-in section automatically?

There is no restore command. Deletion has no undo; recreate it from a preset or your own history.