Penpot Documentation

The Penpot documentation site uses the following tools for content generation and diagramming:

• Static Site Generator: Eleventy (11ty)
• Diagramming (PlantUML): Uses markdown-it-plantuml with plantuml.
• Diagramming (SVG/Mermaid): Uses markdown-it-diagrams with svgbob and mermaid.
• Architecture Templates: Uses arc42 templates and c4model (with C4-PlantUML) for software architecture diagrams.

Penpot uses buckets as internal logical groupings (not to be confused with S3 buckets). Buckets allow the storage module to apply special logic, such as custom storage paths or specific reference-checking rules.

Deduplication (Content Hashing): To save space, Penpot shares duplicated objects. When an object is uploaded, its content is hashed. If a matching hash is found within the same bucket, the existing StorageObject is reused instead of creating a new one. This means multiple unrelated assets may share the same :object-id.

A Penpot File contains a central data attribute that holds its core content. This content is organized into several specialized lists that are modeled as distinct entities due to their complex business logic:

• Pages: The primary layout containers within a file.
• Components: Reusable design elements.
• Colors: The color palette/assets used in the file.
• MediaItems: Embedded media assets.
• Typographies: Font and text style assets.

Team invitations use the /auth/verify-token frontend view. The invitation link contains a token that includes the invited email address.

When the link is followed:

1. The token is verified.
2. The system determines if the email belongs to an existing account or requires a new one.
3. The :register-profile or :login services are invoked.
4. The invitation token is attached so the resulting profile is correctly linked to the team.

Penpot leverages a shared codebase between the frontend and backend by using the same language (Clojure/ClojureScript). To handle environment-specific differences (e.g., Clojure+Java vs. ClojureScript+JS), Penpot uses conditional compilation with the #? construct.

When writing code that must behave differently in the backend (CLJ) versus the frontend (CLJS), use the following syntax:

(defn ordered-set?
  [o]
  #?(:cljs (instance? lks/LinkedSet o)
     :clj (instance? LinkedSet o)))

The development environment uses tmux to manage multiple service windows. You can navigate between them using the prefix Ctrl+b.

Window Mapping

• Window 0 (gulp): Handles building and watching styles, images, fonts, and templates.
• Window 1 (frontend): Handles shadow-cljs compilation for the frontend Clojurescript code.
• Window 2 (exporter): Handles shadow-cljs compilation for the exporter.
• Window 3 (backend): Runs the backend JVM process.

Essential tmux Shortcuts

• Ctrl+b 0 through Ctrl+b 3: Switch to a specific window.
• Ctrl+b c: Create a new shell window.
• Ctrl+b w: Switch between windows (window list).
• Ctrl+b &: Kill the current window.

In Penpot, both Pages and Components share similar logic and structures, so they are both modeled as a Container entity.

• Container: An abstraction representing either a Page or a Component.
• ShapeTree: A hierarchical set of shapes within a Container. The top-level frame contains top-level shapes (frames or others), and these can contain nested non-frame shapes.

When modifying Penpot's data structures (e.g., adding attributes to shapes), follow these core principles to maintain integrity during file export/import and model evolution:

• Prefer Optional Attributes: Design page and shape attributes to be optional. A feature should be activated by the presence of an attribute (e.g., if fill-color is absent, the shape is not filled).
• Avoid null for Default States: When reverting an attribute to its default state, remove the key entirely rather than setting it to null. Many processes, including import/export, filter out null attributes. null is not considered a distinct state from the absence of the attribute.
• Naming Conventions: Do not use special Clojure symbols in object attribute names (e.g., do not end boolean keys with ?), as this can cause issues during export.

Penpot supports multiple authentication methods implemented as distinct backends. A user's profile stores the initial backend used for registration (for auditing), but users can log in using other methods later if the email address matches an existing profile.

Supported backends:

• penpot: Internal registration using email and password.
• ldap: Authentication via an external LDAP directory.
• oidc, google, github, gitlab: Authentication via external services using the OpenID Connect protocol. Penpot includes a generic OIDC handler and preconfigured handlers for popular providers.