mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-24 04:15:14 +00:00
feat(skills): add excalidraw-diagram-generator skill and docs update
This commit is contained in:
jun-shiromizu
193
skills/excalidraw-diagram-generator/scripts/README.md
Normal file
193
skills/excalidraw-diagram-generator/scripts/README.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Excalidraw Library Tools
|
||||
|
||||
This directory contains scripts for working with Excalidraw libraries.
|
||||
|
||||
## split-excalidraw-library.py
|
||||
|
||||
Splits an Excalidraw library file (`*.excalidrawlib`) into individual icon JSON files for efficient token usage by AI assistants.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.6 or higher
|
||||
- No additional dependencies required (uses only standard library)
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
python split-excalidraw-library.py <path-to-library-directory>
|
||||
```
|
||||
|
||||
### Step-by-Step Workflow
|
||||
|
||||
1. **Create library directory**:
|
||||
```bash
|
||||
mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons
|
||||
```
|
||||
|
||||
2. **Download and place library file**:
|
||||
- Visit: https://libraries.excalidraw.com/
|
||||
- Search for "AWS Architecture Icons" and download the `.excalidrawlib` file
|
||||
- Rename it to match the directory name: `aws-architecture-icons.excalidrawlib`
|
||||
- Place it in the directory created in step 1
|
||||
|
||||
3. **Run the script**:
|
||||
```bash
|
||||
python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
|
||||
```
|
||||
|
||||
### Output Structure
|
||||
|
||||
The script creates the following structure in the library directory:
|
||||
|
||||
```
|
||||
skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
|
||||
aws-architecture-icons.excalidrawlib # Original file (kept)
|
||||
reference.md # Generated: Quick reference table
|
||||
icons/ # Generated: Individual icon files
|
||||
API-Gateway.json
|
||||
CloudFront.json
|
||||
EC2.json
|
||||
S3.json
|
||||
...
|
||||
```
|
||||
|
||||
### What the Script Does
|
||||
|
||||
1. **Reads** the `.excalidrawlib` file
|
||||
2. **Extracts** each icon from the `libraryItems` array
|
||||
3. **Sanitizes** icon names to create valid filenames (spaces → hyphens, removes special characters)
|
||||
4. **Saves** each icon as a separate JSON file in the `icons/` directory
|
||||
5. **Generates** a `reference.md` file with a table mapping icon names to filenames
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Token Efficiency**: AI can first read the lightweight `reference.md` to find relevant icons, then load only the specific icon files needed
|
||||
- **Organization**: Icons are organized in a clear directory structure
|
||||
- **Extensibility**: Users can add multiple library sets side-by-side
|
||||
|
||||
### Recommended Workflow
|
||||
|
||||
1. Download desired Excalidraw libraries from https://libraries.excalidraw.com/
|
||||
2. Run this script on each library file
|
||||
3. Move the generated folders to `../libraries/`
|
||||
4. The AI assistant will use `reference.md` files to locate and use icons efficiently
|
||||
|
||||
### Library Sources (Examples — verify availability)
|
||||
|
||||
- Examples found on https://libraries.excalidraw.com/ may include cloud/service icon sets.
|
||||
- Availability changes over time; verify the exact library names on the site before use.
|
||||
- This script works with any valid `.excalidrawlib` file you provide.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**Error: File not found**
|
||||
- Check that the file path is correct
|
||||
- Make sure the file has a `.excalidrawlib` extension
|
||||
|
||||
**Error: Invalid library file format**
|
||||
- Ensure the file is a valid Excalidraw library file
|
||||
- Check that it contains a `libraryItems` array
|
||||
|
||||
### License Considerations
|
||||
|
||||
When using third-party icon libraries:
|
||||
- **AWS Architecture Icons**: Subject to AWS Content License
|
||||
- **GCP Icons**: Subject to Google's terms
|
||||
- **Other libraries**: Check each library's license
|
||||
|
||||
This script is for personal/organizational use. Redistribution of split icon files should comply with the original library's license terms.
|
||||
|
||||
## add-icon-to-diagram.py
|
||||
|
||||
Adds a specific icon from a split Excalidraw library into an existing `.excalidraw` diagram. The script handles coordinate translation and ID collision avoidance, and can optionally add a label under the icon.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.6 or higher
|
||||
- A diagram file (`.excalidraw`)
|
||||
- A split icon library directory (created by `split-excalidraw-library.py`)
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
python add-icon-to-diagram.py <diagram-path> <icon-name> <x> <y> [OPTIONS]
|
||||
```
|
||||
|
||||
**Options**
|
||||
- `--library-path PATH` : Path to the icon library directory (default: `aws-architecture-icons`)
|
||||
- `--label TEXT` : Add a text label below the icon
|
||||
-- `--use-edit-suffix` : Edit via `.excalidraw.edit` to avoid editor overwrite issues (enabled by default; pass `--no-use-edit-suffix` to disable)
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Add EC2 icon at position (400, 300)
|
||||
python add-icon-to-diagram.py diagram.excalidraw EC2 400 300
|
||||
|
||||
# Add VPC icon with label
|
||||
python add-icon-to-diagram.py diagram.excalidraw VPC 200 150 --label "VPC"
|
||||
|
||||
# Safe edit mode is enabled by default (avoids editor overwrite issues)
|
||||
# Use `--no-use-edit-suffix` to disable
|
||||
python add-icon-to-diagram.py diagram.excalidraw EC2 500 300
|
||||
|
||||
# Add icon from another library
|
||||
python add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
|
||||
--library-path libraries/gcp-icons --label "API Server"
|
||||
```
|
||||
|
||||
### What the Script Does
|
||||
|
||||
1. **Loads** the icon JSON from the library’s `icons/` directory
|
||||
2. **Calculates** the icon’s bounding box
|
||||
3. **Offsets** all coordinates to the target position
|
||||
4. **Generates** unique IDs for all elements and groups
|
||||
5. **Appends** the transformed elements to the diagram
|
||||
6. **(Optional)** Adds a label beneath the icon
|
||||
|
||||
---
|
||||
|
||||
## add-arrow.py
|
||||
|
||||
Adds a straight arrow between two points in an existing `.excalidraw` diagram. Supports optional labels and line styles.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.6 or higher
|
||||
- A diagram file (`.excalidraw`)
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
python add-arrow.py <diagram-path> <from-x> <from-y> <to-x> <to-y> [OPTIONS]
|
||||
```
|
||||
|
||||
**Options**
|
||||
- `--style {solid|dashed|dotted}` : Line style (default: `solid`)
|
||||
- `--color HEX` : Arrow color (default: `#1e1e1e`)
|
||||
- `--label TEXT` : Add a text label on the arrow
|
||||
-- `--use-edit-suffix` : Edit via `.excalidraw.edit` to avoid editor overwrite issues (enabled by default; pass `--no-use-edit-suffix` to disable)
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Simple arrow
|
||||
python add-arrow.py diagram.excalidraw 300 200 500 300
|
||||
|
||||
# Arrow with label
|
||||
python add-arrow.py diagram.excalidraw 300 200 500 300 --label "HTTPS"
|
||||
|
||||
# Dashed arrow with custom color
|
||||
python add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"
|
||||
|
||||
# Safe edit mode is enabled by default (avoids editor overwrite issues)
|
||||
# Use `--no-use-edit-suffix` to disable
|
||||
python add-arrow.py diagram.excalidraw 300 200 500 300
|
||||
```
|
||||
|
||||
### What the Script Does
|
||||
|
||||
1. **Creates** an arrow element from the given coordinates
|
||||
2. **(Optional)** Adds a label near the arrow midpoint
|
||||
3. **Appends** elements to the diagram
|
||||
4. **Saves** the updated file
|
||||
Reference in New Issue
Block a user