mirror of
https://github.com/penpot/penpot-export.git
synced 2025-01-02 04:40:05 -05:00
docs: update documentation with a start guide
This commit is contained in:
Roberto Redradix
parent
3cd0c13224
commit
25b08f6373
3 changed files with 109 additions and 32 deletions
127
README.md
127
README.md
|
|
@ -1,27 +1,61 @@
|
|||
# penpot-export
|
||||
|
||||
## Description
|
||||
`penpot-export` is a tool designed to export your design tokens created in Penpot into ready-to-use code or parseable data files.
|
||||
|
||||
`penpot-export` is a tool designed to export your design components created in Penpot directly to CSS files. With a simple `penpot-export` command, you can convert your designs into ready-to-use CSS declarations.
|
||||
Currently, it is able to export page components as CSS and SCSS declarations, and typography and colors assets as CSS, SCSS or JSON (following the [Second Editor' Draft](https://second-editors-draft.tr.designtokens.org/format/) of the [W3C Design Tokens Community Group](https://github.com/design-tokens/community-group) format spec).
|
||||
|
||||
## Installation
|
||||
|
||||
To install `penpot-export`, simply run:
|
||||
## 📦 Packages
|
||||
|
||||
[`@penpot-export/cli`](./packages/cli/) ([npm package](https://www.npmjs.com/package/@penpot-export/cli)) is a CLI tool to use `penpot-export` through the command line. It features a configuration file where you declare what will be exported, where in the file system and what format will use.
|
||||
|
||||
[`@penpot-export/core`](./packages/core/) ([npm package](https://www.npmjs.com/package/@penpot-export/core)) contains the core functionality to retrieve the Penpot data, transform it and output it to the filesystem.
|
||||
|
||||
[demos](./packages/demos/) is a demostrative private package that contains some examples of how to use `@penpot-export/cli`.
|
||||
|
||||
|
||||
## 🧑💻 Usage
|
||||
|
||||
### ⬇️ Installation
|
||||
|
||||
The recommended way to install the `penpot-export` CLI is as a development dependency on a project:
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm install @penpot-export/cli --save-dev
|
||||
|
||||
# yarn
|
||||
yarn add @penpot-export/cli
|
||||
yarn add @penpot-export/cli --dev
|
||||
```
|
||||
|
||||
## Configuration
|
||||
### 🔧 Configuration
|
||||
|
||||
Before you can use `penpot-export`, you need to set up a [`penpot-export.config.js`](./packages/demo/penpot-export.config.js) file at the root of your project. This file defines how your Penpot designs will be exported.
|
||||
`penpot-export` uses the Penpot public API of [a Penpot instance of your choice](https://help.penpot.app/user-guide/introduction/quickstart/). Before you can use `penpot-export`, you'll need a way to authenticate to that API. [Generate an access token](https://help.penpot.app/technical-guide/integration/#access-tokens) and save that value in a safe place.
|
||||
|
||||
Configuration example:
|
||||
You'll also need the file ID of an existing Penpot file in that Penpot instance. Open the Penpot file in your browser and copy the URL. Then run:
|
||||
|
||||
```sh
|
||||
penpot-export inspect <YOUR FILE URL HERE>
|
||||
```
|
||||
|
||||
It'll output something similar to this:
|
||||
|
||||
```
|
||||
The following details are the result of inspecting the provided URL:
|
||||
Penpot instance: https://design.penpot.app/
|
||||
Workspace id: f542b13d-6fc1-8116-8002-fc0aaa3627ae
|
||||
File id: 52961d58-0a92-80c2-8003-2fc8ab8b34dd
|
||||
Page id: 38f1e350-296d-80f1-8002-fd390f93b03d
|
||||
```
|
||||
|
||||
Grab the file ID and the Penpot instance.
|
||||
|
||||
With this, set up a `penpot-export.config.js` file at the root of your project declaring how your Penpot designs will be exported.
|
||||
|
||||
<details>
|
||||
<summary> Example config file</summary>
|
||||
|
||||
`penpot-export.config.js`:
|
||||
```js
|
||||
// @ts-check
|
||||
require('dotenv').config()
|
||||
|
|
@ -37,25 +71,28 @@ const config = {
|
|||
instance: process.env.PENPOT_BASE_URL || undefined,
|
||||
accessToken: process.env.PENPOT_ACCESS_TOKEN,
|
||||
files: [
|
||||
{
|
||||
fileId: 'abea3ef6-4c19-808a-8003-01370d9cb586',
|
||||
pages: [
|
||||
{
|
||||
pageId: '71b1702b-2eb1-81d6-8002-f82a5f182088',
|
||||
output: 'src/styles/ui.css', // 👈 Path where your CSS file should be generated.
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
fileId: '4a499800-872e-80e1-8002-fc0b585dc061',
|
||||
colors: [
|
||||
{
|
||||
output: 'src/styles/colors.css', // 👈 Path where your CSS file should be generated.
|
||||
format: 'scss',
|
||||
output: 'src/styles/colors.css', // 👈 Path where your colors SCSS file should be generated.
|
||||
},
|
||||
],
|
||||
typographies: [
|
||||
{
|
||||
output: 'src/styles/typographies.css', // 👈 Path where your CSS file should be generated.
|
||||
format: 'json',
|
||||
output: 'src/styles/typographies.css', // 👈 Path where your typographies JSON file should be generated.
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
fileId: 'abea3ef6-4c19-808a-8003-01370d9cb586',
|
||||
pages: [
|
||||
{
|
||||
pageId: '71b1702b-2eb1-81d6-8002-f82a5f182088',
|
||||
format: 'css',
|
||||
output: 'src/styles/ui.css', // 👈 Path where your page components CSS file should be generated.
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
@ -64,8 +101,39 @@ const config = {
|
|||
|
||||
module.exports = config
|
||||
```
|
||||
</details>
|
||||
|
||||
## Usage
|
||||
<details>
|
||||
<summary>Configuration schema</summary>
|
||||
|
||||
Config schema:
|
||||
|
||||
property | type | notes
|
||||
-------- | ---- | -----
|
||||
`instance` | (optional) string | Defaults to https://design.penpot.app
|
||||
`accessToken` | string | The access token used to authenticate to the instance above
|
||||
`files` | FileConfig object | A list of files to export, each with its own configuration
|
||||
|
||||
FileConfig schema:
|
||||
|
||||
property | type | notes
|
||||
-------- | ---- | -----
|
||||
`fileId` | string | The UUID of the file where assets will be exported
|
||||
`colors` | (optional) ColorsConfig | A list of outputs for color assets
|
||||
`typographies` | (optional) TypographiesConfig | A list of outputs for typography assets
|
||||
`pages` | (optional) PagesConfig | A list of outputs for page components
|
||||
|
||||
AssetConfig (ColorsConfig, TypographiesConfig, PagesConfig) schema:
|
||||
|
||||
property | type | notes
|
||||
-------- | ---- | -----
|
||||
`output` | string | Relative route where your file should be generated
|
||||
`format` | `css`|`scss`|`json` | Desired format to be generated
|
||||
`fileId` | string (only for PagesConfig) | The UUID of the page from where components will be exported
|
||||
|
||||
</details>
|
||||
|
||||
### ▶️ Usage
|
||||
|
||||
Once you've set up the `penpot-export.config.js` file, simply run the following command to generate your CSS files:
|
||||
|
||||
|
|
@ -73,34 +141,29 @@ Once you've set up the `penpot-export.config.js` file, simply run the following
|
|||
penpot-export
|
||||
```
|
||||
|
||||
This will read your Penpot designs and generate CSS files in the places specified in your configuration file.
|
||||
This will read your Penpot design file and generate the declared files.
|
||||
|
||||
## Development
|
||||
|
||||
## ⌨️ Development
|
||||
|
||||
### Using Yarn Workspaces
|
||||
|
||||
This project utilizes [Yarn Workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/) to manage multiple packages within a single repository. This allows us to house the source code of the penpot-export modules and a demo in separate packages, streamlining development and testing.
|
||||
This project is written in TypeScript and utilizes [Yarn Workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/) to manage multiple packages within a single repository. This allows us to house the source code of the `penpot-export` modules and demos in separate packages, streamlining development and testing.
|
||||
|
||||
> **Why Yarn Workspaces?**
|
||||
|
||||
> _Your dependencies can be linked together, which means that your workspaces can depend on one another while always using the most up-to-date code available._ - [Reference](https://classic.yarnpkg.com/lang/en/docs/workspaces/#toc-why-would-you-want-to-do-this)
|
||||
|
||||
### Package Structure
|
||||
|
||||
- [**packages/core**](./packages/core/): This package contains the tool written in TypeScript. This is where the primary tool code resides.
|
||||
- [**packages/cli**](./packages/cli/): This package contains the CLI tool written in TypeScript.
|
||||
- [**packages/demo**](./packages/demo/): This package serves as a demonstration environment. You can run the `penpot-export` command within this package to test out implementations in development.
|
||||
|
||||
### Local Development
|
||||
|
||||
For the "demo" package to utilize the local version of the `penpot-export` command you're developing, it's essential first to compile the TypeScript code from the "penpot-export" package.
|
||||
For the "demos" package to utilize the local version of the `penpot-export` command you're developing, it's essential first to compile the TypeScript code from the `penpot-export` package.
|
||||
|
||||
### Handy Commands
|
||||
|
||||
To facilitate the development process, we've set up the following commands that can be run at the repository's root:
|
||||
|
||||
- **yarn dev**: Runs the CLI tool in development mode. Ideal for making changes and seeing real-time results.
|
||||
- **yarn build**: Compiles the TypeScript code in production mode. Ensure you run this command before testing the tool in the "demo" package.
|
||||
- **yarn demo**: Runs the `penpot-export` command within the "demo" package. It's handy for quickly testing implementations after making changes to the source code.
|
||||
- **yarn build**: Compiles the TypeScript code in production mode. Ensure you run this command before testing the tool in the `demos` package.
|
||||
- **yarn demo**: Runs the `penpot-export` command within the `demos` package per demo. It's handy for quickly testing implementations after making changes to the source code.
|
||||
|
||||
We recommend following this workflow: make changes to the code, run `yarn build`, and then `yarn demo` to test your changes.
|
||||
|
|
|
|||
7
packages/cli/README.md
Normal file
7
packages/cli/README.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# @penpot-export/cli
|
||||
|
||||
`penpot-export` is a tool designed to export your design tokens created in Penpot into ready-to-use code or parseable data files.
|
||||
|
||||
This package houses the code for the CLI tool to use `penpot-export` through the command line.
|
||||
|
||||
Refer to the [full documentation](https://github.com/penpot/penpot-export) for usage notes.
|
||||
7
packages/core/README.md
Normal file
7
packages/core/README.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# @penpot-export/core
|
||||
|
||||
`penpot-export` is a tool designed to export your design tokens created in Penpot into ready-to-use code or parseable data files.
|
||||
|
||||
This package houses the code for the core functionality of `penpot-export`.
|
||||
|
||||
Refer to the [full documentation](https://github.com/penpot/penpot-export) for usage notes.
|
||||
Loading…
Reference in a new issue