|
| 1 | +--- |
| 2 | +description: Add 1px grey borders to PNG images in a documentation file. |
| 3 | +--- |
| 4 | + |
| 5 | +# Usage |
| 6 | + |
| 7 | +`/add-borders <doc-file-path>` |
| 8 | + |
| 9 | +Analyze PNG images referenced in the specified markdown file at {{arg}} and add 1px #999999 (medium grey) borders to any images that don't already have them. This improves visual clarity and consistency of screenshots and diagrams in documentation. |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Process |
| 14 | + |
| 15 | +### 1. Verify prerequisites |
| 16 | + |
| 17 | +Before running the border tool, ensure dependencies are installed: |
| 18 | + |
| 19 | +```bash |
| 20 | +cd /workspaces/src/pulumi/docs/scripts/image-borders && pipenv install |
| 21 | +``` |
| 22 | + |
| 23 | +If this is the first run or if Pillow is not yet installed, the installation will complete automatically. |
| 24 | + |
| 25 | +### 2. Run the border addition tool |
| 26 | + |
| 27 | +Execute the Python script with the provided documentation file: |
| 28 | + |
| 29 | +```bash |
| 30 | +cd /workspaces/src/pulumi/docs && pipenv run python scripts/image-borders/add_borders.py {{arg}} |
| 31 | +``` |
| 32 | + |
| 33 | +The script will: |
| 34 | +- Parse the markdown file to find all PNG image references |
| 35 | +- Check each image's edge pixels to detect existing borders |
| 36 | +- Add a 1px #999999 border to images that don't have one |
| 37 | +- Skip images that already have a grey border (within tolerance) |
| 38 | +- Display a summary of modified and skipped images |
| 39 | + |
| 40 | +### 3. Review the results |
| 41 | + |
| 42 | +The script outputs: |
| 43 | +- **Modified**: Images that received new borders |
| 44 | +- **Skipped**: Images that already had borders |
| 45 | + |
| 46 | +Example output: |
| 47 | +``` |
| 48 | +Found 3 PNG image(s) |
| 49 | +
|
| 50 | +✓ Added border: content/docs/esc/assets/create-environment.png |
| 51 | +✓ Added border: content/docs/esc/assets/editor-before-save.png |
| 52 | +⊘ Skipped (has border): content/docs/esc/assets/editor-after-save.png |
| 53 | +
|
| 54 | +Summary: |
| 55 | + Modified: 2 |
| 56 | + Skipped: 1 |
| 57 | +``` |
| 58 | + |
| 59 | +### 4. Verify the changes |
| 60 | + |
| 61 | +After borders are added: |
| 62 | +1. View the modified images to ensure borders look correct |
| 63 | +2. Check that border width and color (#CCCCCC) are appropriate |
| 64 | +3. Verify the images still display correctly in the documentation |
| 65 | + |
| 66 | +You can preview the documentation locally: |
| 67 | +```bash |
| 68 | +make serve |
| 69 | +``` |
| 70 | + |
| 71 | +Then navigate to the affected page at http://localhost:1313 |
| 72 | + |
| 73 | +### 5. Commit the changes (if appropriate) |
| 74 | + |
| 75 | +If the borders improve the documentation quality, commit the modified images: |
| 76 | + |
| 77 | +```bash |
| 78 | +git add <image-files> |
| 79 | +git commit -m "Add 1px borders to documentation images for visual clarity" |
| 80 | +``` |
| 81 | + |
| 82 | +--- |
| 83 | + |
| 84 | +## Options |
| 85 | + |
| 86 | +The script supports additional options: |
| 87 | + |
| 88 | +- `--dry-run` - Show what would be done without making changes |
| 89 | +- `--repo-root <path>` - Specify repository root (auto-detected by default) |
| 90 | + |
| 91 | +Example with dry run: |
| 92 | +```bash |
| 93 | +pipenv run python scripts/image-borders/add_borders.py {{arg}} --dry-run |
| 94 | +``` |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## Notes |
| 99 | + |
| 100 | +- The script uses edge pixel analysis to detect existing borders with 80% confidence threshold |
| 101 | +- Handles RGBA images (preserves transparency) |
| 102 | +- Uses #999999 (medium grey) for visibility on both white and light backgrounds |
| 103 | +- Only processes PNG files (ignores JPG, GIF, SVG, etc.) |
| 104 | +- Modifies images in place (use git to revert if needed) |
0 commit comments