mirror of
https://github.com/penpot/penpot.git
synced 2026-08-01 10:01:38 -04:00
4c7863d6c8
* 📚 Add comprehensive documentation for .penpot file format (v3) Create user-facing documentation for the .penpot binfile format to help developers and power users understand and inspect the ZIP+JSON structure. - Add technical specification with complete schema reference for all JSON files (manifest, file metadata, pages, shapes, library assets, storage objects, plugin data) - Add user-friendly overview explaining the format structure, inspection methods, and version history - Update export-import-files.njk to clarify current format is not deprecated and note that v2 was never released - Add cross-links between documentation pages - Include source code references to authoritative malli schemas AI-assisted-by: qwen3.7-plus * 📎 Add playwright dependency to the root package.json * 📚 Add browser based .penpot file inspector to docs Add a client-side, no-build inspector for .penpot (v3) files. The tool runs entirely in the browser: JSZip is loaded lazily from a CDN, the file is never uploaded. It provides a collapsible file tree, syntax- highlighted JSON viewer with search, image previews, a summary panel with file/shape/storage counts, shape summary cards with color swatches, and clickable UUID cross-references with backlinks. The inspector is added at docs/technical-guide/developer/data-model/penpot-file-inspector.njk and linked from the format spec and the user-facing format page. AI-assisted-by: minimax-m3 * 📚 Use full page width and 2-column layout for inspector The inspector previously sat inside the docs site's 42rem content column, which forced a stacked layout and wasted the wide viewport. - Hide the docs page-navigation sidebar on this page via :has() - Use a 2-column CSS grid: file tree (280px, sticky) on the left, content (flex: 1) on the right - Restore the directory tree as a permanent left-rail navigation (it was removed when the picker was first introduced, then added back as a collapsible panel; a sticky rail is a better fit now that horizontal space is plentiful) - Remove the tree toggle button — the tree is always visible - Collapses to 1 column on viewports below 900px AI-assisted-by: minimax-m3 * 💄 Indent nested JSON values in inspector The JSON tree view in the inspector was rendering all properties at the same indent level, making it hard to see which values were nested inside objects or arrays. Root-level properties and deeply nested ones looked identical. Add padding-left and a subtle vertical guide line to .jchildren so each nesting level is visually distinct. Bump the toggle column to 1.2em and add a touch of vertical padding to .jrow for breathing room. AI-assisted-by: minimax-m3
156 lines
6.7 KiB
Plaintext
156 lines
6.7 KiB
Plaintext
---
|
|
title: The .penpot file format
|
|
order: 2
|
|
desc: Understand the .penpot file format, what's inside, and how to inspect your design files.
|
|
---
|
|
|
|
<h1 id="penpot-file-format">The .penpot file format</h1>
|
|
<p class="main-paragraph">Penpot's native file format is designed to be open, inspectable, and efficient. Unlike proprietary formats, you can always look inside a .penpot file to understand your design data.</p>
|
|
|
|
<h2 id="what-is-penpot-format">What is a .penpot file?</h2>
|
|
|
|
<p>A <code class="language-text">.penpot</code> file is a <strong>ZIP archive</strong> containing:</p>
|
|
<ul>
|
|
<li><strong>JSON metadata</strong> — human-readable descriptions of your pages, shapes, colors, components, and more</li>
|
|
<li><strong>Binary media files</strong> — images, fonts, and other assets used in your design</li>
|
|
</ul>
|
|
|
|
<p>This means your design data is never locked in a proprietary format. You can always unzip a .penpot file and read the JSON to understand what's inside.</p>
|
|
|
|
<h2 id="whats-inside">What's inside a .penpot file?</h2>
|
|
|
|
<p>When you unzip a .penpot file, you'll find this structure:</p>
|
|
|
|
<figure>
|
|
<pre class="language-text"><code>your-design.penpot (ZIP archive)
|
|
├── manifest.json ← Table of contents
|
|
├── files/ ← Your design data
|
|
│ ├── file-metadata.json
|
|
│ └── file-data/
|
|
│ ├── pages/ ← Each page of your design
|
|
│ ├── colors/ ← Library colors
|
|
│ ├── components/ ← Library components
|
|
│ ├── typographies/ ← Library typographies
|
|
│ ├── tokens.json ← Design tokens
|
|
│ └── media/ ← Media references
|
|
└── objects/ ← Images and binary assets</code></pre>
|
|
</figure>
|
|
|
|
<h3>manifest.json</h3>
|
|
<p>The manifest is the table of contents. It tells you:</p>
|
|
<ul>
|
|
<li>Which version of the format is used</li>
|
|
<li>Which Penpot version created the file</li>
|
|
<li>What files are included</li>
|
|
<li>What features are enabled</li>
|
|
</ul>
|
|
|
|
<h3>File data</h3>
|
|
<p>The <code class="language-text">files/</code> directory contains all your design data organized by type:</p>
|
|
<ul>
|
|
<li><strong>Pages</strong> — Each page is split into individual shape files for efficiency</li>
|
|
<li><strong>Colors</strong> — Your color library with hex values, gradients, or image fills</li>
|
|
<li><strong>Components</strong> — Reusable component definitions</li>
|
|
<li><strong>Typographies</strong> — Text style definitions</li>
|
|
<li><strong>Tokens</strong> — Design tokens organized in sets and themes</li>
|
|
<li><strong>Media</strong> — References to images and other assets</li>
|
|
</ul>
|
|
|
|
<h3>Objects</h3>
|
|
<p>The <code class="language-text">objects/</code> directory contains the actual binary files (PNG, JPG, SVG) referenced by your design. Each object has a JSON metadata file alongside the binary file.</p>
|
|
|
|
<h2 id="how-to-inspect">How to inspect a .penpot file</h2>
|
|
|
|
<p>Since .penpot files are just ZIP archives, you can inspect them with standard tools.</p>
|
|
|
|
<h3>On macOS or Linux</h3>
|
|
|
|
<p><strong>1. List the contents without extracting:</strong></p>
|
|
<pre class="language-bash"><code>unzip -l your-design.penpot</code></pre>
|
|
|
|
<p><strong>2. Extract to a temporary folder:</strong></p>
|
|
<pre class="language-bash"><code>unzip your-design.penpot -d /tmp/penpot-inspect</code></pre>
|
|
|
|
<p><strong>3. View the manifest:</strong></p>
|
|
<pre class="language-bash"><code>cat /tmp/penpot-inspect/manifest.json | jq .</code></pre>
|
|
|
|
<p><strong>4. Browse the structure:</strong></p>
|
|
<pre class="language-bash"><code>tree /tmp/penpot-inspect</code></pre>
|
|
|
|
<p><strong>5. View a specific shape:</strong></p>
|
|
<pre class="language-bash"><code>cat /tmp/penpot-inspect/files/*/pages/*/*.json | jq .</code></pre>
|
|
|
|
<h3>On Windows</h3>
|
|
|
|
<p><strong>1. Right-click the .penpot file</strong> and select "Extract All..." or use 7-Zip.</p>
|
|
|
|
<p><strong>2. Browse the extracted folder</strong> to see the structure.</p>
|
|
|
|
<p><strong>3. Open any JSON file</strong> with a text editor or use a JSON viewer tool.</p>
|
|
|
|
<h3>Using AI tools</h3>
|
|
|
|
<p>You can use the <a href="/mcp/">Penpot MCP server</a> to inspect .penpot files with AI assistance. The MCP server can read and analyze your design files, making it easy to understand complex designs or automate tasks.</p>
|
|
|
|
<h2 id="versioning">Format versions</h2>
|
|
|
|
<p>The .penpot format has evolved over time:</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Version</th>
|
|
<th>Description</th>
|
|
<th>Status</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><strong>v3</strong></td>
|
|
<td>ZIP + JSON format (current)</td>
|
|
<td>✅ Current</td>
|
|
</tr>
|
|
<tr>
|
|
<td>v1</td>
|
|
<td>Custom binary format</td>
|
|
<td>⚠️ Deprecated</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p class="advice">All current Penpot versions export in v3 format. Old v1 files can still be imported, but new exports will use v3.</p>
|
|
|
|
<h3>Version numbers inside the file</h3>
|
|
|
|
<p>Inside a .penpot file, you'll see two different version numbers:</p>
|
|
|
|
<ul>
|
|
<li><strong>Format version</strong> (in <code class="language-text">manifest.json</code>) — Tracks changes to the ZIP structure itself. Currently <code class="language-text">1</code>.</li>
|
|
<li><strong>Data version</strong> (in each file's JSON) — Tracks changes to the data model. This number increases as Penpot evolves.</li>
|
|
</ul>
|
|
|
|
<h3>Feature flags</h3>
|
|
|
|
<p>Files also include a list of <strong>feature flags</strong> that indicate which capabilities are used. For example:</p>
|
|
|
|
<ul>
|
|
<li><code class="language-text">design-tokens/v1</code> — Uses design tokens</li>
|
|
<li><code class="language-text">components/v2</code> — Uses the v2 component system</li>
|
|
<li><code class="language-text">variants/v1</code> — Uses component variants</li>
|
|
<li><code class="language-text">layout/grid</code> — Uses grid layouts</li>
|
|
</ul>
|
|
|
|
<p>These flags help Penpot know what features need to be supported when importing the file.</p>
|
|
|
|
<h2 id="for-developers">For developers</h2>
|
|
|
|
<p>If you're building tools or integrations that work with .penpot files, the <a href="/technical-guide/developer/data-model/penpot-file-format/">complete technical specification</a> provides detailed schema definitions for every JSON file in the archive.</p>
|
|
|
|
<p>Key resources:</p>
|
|
<ul>
|
|
<li><a href="/technical-guide/developer/data-model/penpot-file-format/">Technical specification</a> — Complete schema reference</li>
|
|
<li><a href="/technical-guide/developer/data-model/penpot-file-inspector/">File inspector</a> — Browser-based tool to interactively explore a .penpot file</li>
|
|
<li><a href="/mcp/">MCP Server</a> — AI-powered file inspection and manipulation</li>
|
|
<li><a href="/technical-guide/developer/data-model/">Data model</a> — Conceptual overview of Penpot's data structures</li>
|
|
</ul>
|