Skip to content

Commit 60782cc

Browse files
ace-of-acesace-of-aces
committed
feat: vitepress docs
1 parent 74985af commit 60782cc

17 files changed

+2070
-1
lines changed

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,4 @@ _ide_helper_models.php
2727
# Misc
2828
phpunit.xml
2929
phpstan.neon
30-
/docs
3130
/coverage

‎docs/.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
*.log
2+
*.tgz
3+
.DS_Store
4+
.idea
5+
.temp
6+
.vite_opt_cache
7+
.vscode
8+
dist
9+
cache
10+
temp
11+
node_modules

‎docs/.vitepress/config.mts‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
import { defineConfig } from 'vitepress'
2+
import pkg from '../package.json'
3+
4+
// https://vitepress.dev/reference/site-config
5+
export default defineConfig({
6+
title: "Laravel Image Transform URL",
7+
description: "Easy, URL-based image transformations for Laravel inspired by Cloudflare Images.",
8+
srcDir: './pages',
9+
markdown: {
10+
theme: {
11+
light: 'github-light',
12+
dark: 'github-dark'
13+
}
14+
},
15+
themeConfig: {
16+
// https://vitepress.dev/reference/default-theme-config
17+
nav: [
18+
{ text: 'Home', link: '/' },
19+
{
20+
text: pkg.version,
21+
items: [
22+
{
23+
text: 'Changelog',
24+
link: 'https://github.com/ace-of-aces/laravel-image-transform-url/blob/main/CHANGELOG.md'
25+
},
26+
{
27+
text: 'Contributing',
28+
link: 'https://github.com/ace-of-aces/laravel-image-transform-url/blob/main/CONTRIBUTING.md'
29+
}
30+
]
31+
}
32+
],
33+
34+
sidebar: [
35+
{
36+
text: 'Basics',
37+
items: [
38+
{ text: 'Installation', link: '/installation' },
39+
{ text: 'Setup', link: '/setup' },
40+
{ text: 'Getting Started', link: '/getting-started' },
41+
]
42+
},
43+
{
44+
text: 'Options',
45+
items: [
46+
{ text: 'Configuring Options', link: '/configuring-options' },
47+
{ text: 'Available Options', link: '/available-options' },
48+
]
49+
},
50+
{
51+
text: 'Advanced',
52+
items: [
53+
{ text: 'Image Caching', link: '/image-caching' },
54+
{ text: 'Rate Limiting', link: '/rate-limiting' },
55+
{ text: 'CDN Usage', link: '/cdn-usage' },
56+
{ text: 'Error Handling', link: '/error-handling' },
57+
]
58+
}
59+
],
60+
61+
socialLinks: [
62+
{ icon: 'github', link: 'https://github.com/ace-of-aces/laravel-image-transform-url' },
63+
],
64+
65+
footer: {
66+
message: 'Released under the MIT License.',
67+
copyright: 'Copyright © 2025-present Julian Schramm'
68+
},
69+
70+
search: {
71+
provider: 'local',
72+
}
73+
}
74+
})

‎docs/.vitepress/theme/custom.css‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/* .vitepress/theme/custom.css */
2+
:root {
3+
--vp-c-brand-1: #000000;
4+
--vp-c-brand-2: #3d3b3b;
5+
--vp-c-brand-3: #8b8585;
6+
--vp-c-brand-soft: rgba(114, 109, 109, 0.14);
7+
}
8+
9+
.dark {
10+
--vp-c-brand-1: #ffffff;
11+
--vp-c-brand-2: #cbc4c4;
12+
--vp-c-brand-3: #8a8585;
13+
--vp-c-brand-soft: rgba(115, 110, 110, 0.14);
14+
}

‎docs/.vitepress/theme/index.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme'
2+
import './custom.css'
3+
4+
export default DefaultTheme

‎docs/package.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "v0.5.0",
3+
"devDependencies": {
4+
"vitepress": "^1.6.3"
5+
},
6+
"scripts": {
7+
"docs:dev": "vitepress dev",
8+
"docs:build": "vitepress build",
9+
"docs:preview": "vitepress preview"
10+
}
11+
}

‎docs/pages/available-options.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Available Options
2+
3+
These are the options that can be used to transform images with this package.
4+
5+
## `background`
6+
7+
`string`
8+
9+
Set the background color of the image.
10+
Any valid HEX color value (without a leading `#`).
11+
12+
Example:
13+
14+
```
15+
background=ff0000
16+
```
17+
18+
> [!IMPORTANT]
19+
> Only supported for the `png` format.
20+
21+
## `blur`
22+
23+
`integer`
24+
25+
Set the blur level of the image.
26+
Possible values: `0` to `100`.
27+
28+
Example:
29+
30+
```
31+
blur=50
32+
```
33+
34+
> [!CAUTION]
35+
> The `blur` option is a resource-intensive operation and may cause memory issues if the image is too large. It is recommended to use this option with caution and test beforehand, or disable it in the config.
36+
37+
## `contrast`
38+
39+
`integer`
40+
41+
Set the contrast level of the image.
42+
Possible values: `-100` to `100`.
43+
44+
Example:
45+
46+
```
47+
contrast=50
48+
```
49+
50+
## `flip`
51+
52+
`string`
53+
54+
Flip the image.
55+
Possible values: `h` (horizontal), `v` (vertical), `hv` (horizontal and vertical).
56+
57+
Example:
58+
59+
```
60+
flip=h
61+
```
62+
63+
## `format`
64+
65+
`string`
66+
67+
Set the format of the image.
68+
Supported formats: `jpg`, `jpeg`, `png`, `gif`, `webp`.
69+
70+
Example:
71+
72+
```
73+
format=webp
74+
```
75+
76+
## `height`
77+
78+
`integer`
79+
80+
Set the height of the image.
81+
Values greater than the original height will be ignored.
82+
83+
Example:
84+
85+
```
86+
height=250
87+
```
88+
89+
## `quality`
90+
91+
`integer`
92+
93+
Set the quality of the image.
94+
Possible values: `0` to `100`.
95+
96+
Example:
97+
98+
```
99+
quality=80
100+
```
101+
102+
## `version`
103+
104+
`integer`
105+
106+
Version number of the image.
107+
Any positive integer. More info in the [Image Caching](/image-caching) section.
108+
109+
Example:
110+
111+
```
112+
version=2
113+
```
114+
115+
## `width`
116+
117+
`integer`
118+
119+
Set the width of the image.
120+
Values greater than the original width will be ignored.
121+
122+
Example:
123+
124+
```
125+
width=250
126+
```

‎docs/pages/cdn-usage.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Usage with CDNs
2+
3+
The package is designed to work seamlessly with CDNs like Cloudflare, BunnyCDN, and others.
4+
5+
The most important configuration is the [`Cache-Control`](https://developer.mozilla.org/de/docs/Web/HTTP/Reference/Headers/Cache-Control) header, which you can customize to your liking in the `image-transform-url.php` configuration file.
6+
7+
```php
8+
/*
9+
|--------------------------------------------------------------------------
10+
| Response Headers
11+
|--------------------------------------------------------------------------
12+
|
13+
| Below you may configure the response headers which are added to the
14+
| response. This is especially useful for controlling caching behavior
15+
| of CDNs.
16+
|
17+
*/
18+
19+
'headers' => [
20+
'Cache-Control' => env('IMAGE_TRANSFORM_HEADER_CACHE_CONTROL', 'immutable, public, max-age=2592000, s-maxage=2592000'),
21+
// more headers can be added here
22+
],
23+
```

‎docs/pages/configuring-options.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Configuring Options
2+
3+
This package supports a variety of options, but you may not need or want to use all of them. You can configure which options are enabled in the `image-transform-url.php` configuration file.
4+
5+
```php
6+
/*
7+
|--------------------------------------------------------------------------
8+
| Enabled Options
9+
|--------------------------------------------------------------------------
10+
|
11+
| Here you may configure the options which are enabled for the image
12+
| transformer.
13+
|
14+
*/
15+
16+
'enabled_options' => env('IMAGE_TRANSFORM_ENABLED_OPTIONS', [
17+
'width',
18+
'height',
19+
'format',
20+
'quality',
21+
// 'flip',
22+
// 'contrast',
23+
// 'version',
24+
// 'background',
25+
// 'blur'
26+
]),
27+
```

‎docs/pages/error-handling.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Error Handling
2+
3+
The route handler of this package is designed to be robust against invalid options, paths and file names, while also not exposing additional information of your applications public directory structure.
4+
5+
This is why the route handler will return a plain `404` response if:
6+
7+
- a requested image does not exist at the specified path
8+
- the requested image is not a valid image file
9+
- the provided options are not in the correct format (`key=value`, no trailing comma, etc.)
10+
11+
The only other HTTP error that can be returned is a `429` response, which indicates that the request was rate-limited.
12+
13+
If parts of the given route options are invalid, the route handler will ignore them and only apply the valid options.
14+
15+
Example:
16+
17+
```ansi
18+
http://localhost:8000/image-transform/width=250,quality=foo,format=webp/example.jpg
19+
```
20+
21+
will be processed as:
22+
23+
```ansi
24+
http://localhost:8000/image-transform/width=250,format=webp/example.jpg
25+
```

0 commit comments

Comments
 (0)