penpot / penpot-docs

Website and documentation about Penpot, The Open-Source design & prototyping platform

penpot-docs

Penpot documentation website

Usage

To view this site locally, first set up the environment:

nvm install         (if necessary)
nvm use
corepack enable (if necessary)

yarn install

And launch a development server:

yarn run start

You can then point a browser to http://localhost:8080.

Tooling

• Eleventy (11ty)
• Diagrams with plantuml. See also real-world-plantuml.
• Diagrams with svgbob and mermaid.
• arc42 template.
• c4model for software architecture, and an implementation in plantuml.

License

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.

Copyright (c) UXBOX Labs SL

penpot-docs's Issues

404 Not Found when clicking on Developer guide in the footer

The URL it tries to access is: https://help.penpot.app/developer-guide

Finding docker installation instructions is tedious

Hi, I’m a new penpot user. Penpot looks great, thanks for creating it.

I wanted to try running Penpot by using docker.

To get to the Start Penpot section with the 2 command line instructions I needed, I had to navigate 4 pages (and 5 clicks) from the home page. At least one of the links I had to click along the way was far down a page in a forum post.

For a UX product, I think that’s not the best UX ? (pun intended :-))

I think an ideal solution would be a section expanding/appearing when clicking the “self-host install” button right on the homepage that shows the 2 lines to install using docker with a link to more info for those that need it. Perhaps with a different tab for Elestio within that appearing section.

I also think a one-liner pointing to instructions on how to install docker suffices, I had to scroll through all the docker installation instructions I didn’t need a few times along the way. I understand the Penpot audience isn’t developers, but I still think it was too much.

Hope this is useful feedback! Screenshots and details below

https://penpot.app/

https://penpot.app/self-host

https://penpot.app/self-host#installing-options

https://community.penpot.app/t/self-hosting-penpot-ii/2337

https://help.penpot.app/technical-guide/getting-started/#install-with-docker

In devenv, how do I connect to penpot once I start it running?

The documentations describes how to get the devenv working in tmux, but can I connect with a browser?

Connecting to http://localhost:3448/dashboard works, but nothing connects on http://localhost:8888
It doesn't appear to be working.

Install Penpot with Docker and with SSL to access through HTTPS

I tried to read documentation, but I could not find solution there. I think it would be wise to write some steps how to do it.
Thank you.

Authentication via GitLab Oauth: missing redirect URI

In order to use the GitLab Oauth mechanism, you should provide GitLab base URI, the Client ID, and Client secret, values produced from GitLab after the registration of the application. To do that, it's important to define, in the registration phase, the redirect URI.

The documentation (https://help.penpot.app/technical-guide/configuration/#gitlab) actually is missing the value that should be provided to GitLab to handle the redirect after registration/authentication.

I sent an email to your support team that said this value is:
https://yourhostname/api/auth/oauth/gitlab/callback

Please, update the documentation with this information because it can be really important for all companies like ours that use GitLab as auth-mechanism.

Use `docker compose exec` rather than `docker exec -ti`

Compose has a docker compose exec command that's equivalent to docker exec -ti and frees you from having to know/guess/find the name of the container: you just use the name of the service as declared in the compose file and Compose maps it for you.

In https://help.penpot.app/technical-guide/getting-started/#create-users-using-cli, the command can thus be replaced with

docker compose exec penpot-backend python3 ./manage.py create-profile

and the note that follows regarding the exact name of the container can be removed.

Configuration: Storage flags outdated

In the documentation for the image storage, the documentation still has the old ENV variable names, which do not work anymore.

The docker-compose.yml in the penpot repository shows a different configuration:
https://github.com/penpot/penpot/blob/develop/docker/images/config.env#L16-L17

PS: As i also had stumbled upon this just by noticing that my image uploads do not work anymore, I'd like to suggest announcing such breaking changes more visibly in the documentation and the release notes if possible :)

Thank you very much!

plan to translate this document?

If you do, I'd like to help you translate Japanese.

Can't do suggestions after following the instructions

Hi there, I wanted to do some suggestions for completed translations, but after following the instructions the 'Save' and 'Save suggestion' buttons remain disabled. There's a red line saying that I don't have permission to save translations.

Although I wouldn't know why, maybe this is specific to my account. But even then, I'd hope for some guidance in the docs for what to do in such a situation.

PlantUml Error on technical documentation

Issue reported by @rvz420 on the penpot repository: penpot/penpot#4299

Go to https://help.penpot.app/technical-guide/developer/architecture/frontend/

The screenshot shows an error message

assets-db option status unclear

There is a discrepancy in the documentation:

penpot-docs/technical-guide/developer/subsystems/assets-storage.md

Line 21 in 9b46d07

* `:assets-db` stores them inside the PostgreSQL database, in a special table

shows the assets-db as an option.

penpot-docs/technical-guide/configuration.md

Line 295 in 9b46d07

Assets storage is implemented using "plugable" backends. Currently there are three

says "Currently there are three backends available" and then lists only two.

The commit in which "db" is dropped seems to be only about formatting the documentation, so it might actually be dropped from the Configuration Guide by mistake:
f677fee#diff-a5fa29120dd3a682584aead54a908d2ff23175919ad59afd2bb92841f0fdd5a7L280-R294

Basically I would really like to use the assets-db option on an on-prem offline network. This ensures that our database backup strategy also covers the assets and no timing issues can occur between our separate file based backup and database backup processes.

So the main question for me is: is the assets-db option still a viable option? Or was it dropped from the documentation due to some known-issues?

Misleading statement on adaptability

The line "Extreme adaptability: contributions can range from add-ons and plugins to core functionality." is misleading. It implies that Penpot supports add-ons and plugins, but it doesn't.

Optimize the "Libraries & templates" page

I stumbled accross the Libraries and template page as I scanned the comments in a ticket and found this one
https://penpot.app/libraries-templates.html

I haven't used to templates before and wanted to get to know them.
I report my impressions and possible improvements for said page from a UX engineer perspective herein, which I'd deem useful given this onboarding scenario.

I realized that I was supposed to download and to somehow import the libraries. I didn't know how to though in detail.

Reading the links I think it's nice to know that I can contribute, but this targets clearly the "most savvy users", not the novel ones, which want to just use the import.
=> I would consider to place the link "How to contribute" at the third position in that link list.

One of the links lead me to https://help.penpot.app/user-guide/import-export which with the exporting parts.
=> It would be more helpful, if it would either start the other way round
=> alternatlively change the link to jump to https://help.penpot.app/user-guide/import-export/#importing-import
=> additionally consider to remove the "& export" text from the link. It's not relevant to users whether the linked article is also about exporting files or whether that one is separated.

Furthermore, I'd suggest to consider adding a GIF screencast to the wiki article (or probably the page as a popup?), which shows a walkthrough for the import process.

Update information to docs

Hello!

Just a small improvement idea. "How to update" section to the technical guide could be useful. Updating docker containers is probably quite easy, but since I am still learning it, I am afraid of breaking something.

Documentation on REST Interface

Hi,

I am trying to support Penpot in the Luisa framework (https://luisa.cloud). I was trying to reverse engineer the REST API, but for me the data structure is not clear. It´s quite different from the JSON Figma or Sketch produce...

I often see that there or some arrays like

["^ ", "~:y", 113, "~:hide-fill-on-export", false, "^O", 0, "^P",…]

I assume this is a list of key value pairs. But I would like to confirm this. Are there somewhere schema defined?

Cheers,

Klaus

Minor: Wrong link in mailcatcher section on "Development environment"

In

Instead, it stores them in memory and allows to browse them via a web interface similar to a webmail client. Simply navigate to:
http://localhost:1080

The link named actually leads to https://help.penpot.app/technical-guide/developer/devenv/ instead of http://localhost:1080

Section on demo users is inaccurate/outdated

I had to use the option disable-demo-users to disable demo users, but https://help.penpot.app/technical-guide/configuration/#demo-users suggests that the demo users setting is opt-in. It appears to be opt-out as of 1.10.

Add information about upgrading PostgresSQL version in docker container

Based on feedback from @violoncelloCH on issue #4434:

Regarding this issue, I still think it would make sense to have a quick note about the required Postgres version and a reference to https://community.penpot.app/t/how-to-upgrade-postgresql-version-in-docker-container/2104 either in the documentation in the upgrade to v2 section or in the changelog. Thanks for considering this :)

Recommended system requirements

What are the recommended system requirements?

CPU
Amount of RAM
Space

for the penpot run without problems

User guide grammar errors

Hello,

After reviewing Penpot's user guide, I've noticed several grammatical error in the following chapters:

1. User Guide - 14 | Import/Export: "Each format has is advantages and disadvantages, choose what suits better to your case"

Suggestion: "Each format has its advantages and disadvantages; choose what suits your case better."

3. User Guide - 15 | Team: "An owner can transfer her ownership to another team member anytime and has to transfer when leaving the team."

Suggestion: "An owner can transfer their ownership to another team member at any time and must transfer it before leaving the team."

4. User Guide - 16 | Custom Fonts: "To use at Penpot a font that you have at your local machine, you need to upload it first to the Penpot team where you want it."

Suggestion: "To use a font that you have on your local machine, you need to upload it first to the Penpot team where you want to use it."