You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 14, 2023. It is now read-only.
- Namespace change from Kirby\StaticBuilder to KirbyStaticBuilder
6
+
- Class Kirby\StaticBuilder\Controller renamed to KirbyStaticBuilder\Plugin
7
+
- Method Kirby\StaticBuilder\Controller::register now KirbyStaticBuilder\Plugin::register
8
+
- Method Kirby\StaticBuilder\Controller::defaultFilter now KirbyStaticBuilder\Plugin::defaultFilter
9
+
10
+
Configuration changes:
11
+
12
+
- Default URL strategy is now to use relative URLs ('./')
13
+
- Outputdir can now be any *relative* path; some basic checks are in place to avoid overwriting Kirby's standard folders, but please be careful if changing this option!
14
+
- Default page extension is now '/index.html' (writing a page at '[outputdir]/page/url/index.html')
15
+
16
+
Bugfixes:
17
+
18
+
- Probably fixed, we need to check: https://github.com/fvsch/kirby-staticbuilder/issues/24
With default settings you should be able to put the contents of the `static` folder directly on your website’s root.
28
-
29
-
- Page files will look like: `my/page.html`
30
-
- URLs will look like: `/my/page`
31
-
32
-
Make sure that your server config allows serving `my/page.html` when requesting the `/my/page` URL.
33
-
34
-
With Apache, this requires the `Multiviews` options, which you can probably enable in an `.htaccess` file if needed:
12
+
// Extension is disabled by default!
13
+
'staticbuilder' => false,
35
14
36
-
```apache
37
-
Options +Multiviews
38
-
```
39
-
40
-
### Copying page files
15
+
// Pages will we written to: [project_root]/[outputdir]/[page_url][extension]
16
+
// Example with default settings: [project_root]/static/parent-page/child-page/index.html
17
+
'staticbuilder.outputdir' => 'static',
18
+
'staticbuilder.extension' => '/index.html',
41
19
42
-
There are several options for copying page files and making sure that your links and file references still work.
20
+
// Lets you provide an absolute base URL, such as '/' or 'https//domain.tld/'
21
+
// If false, we will try to write relative URLs instead
22
+
'staticbuilder.baseurl' => false,
43
23
44
-
1. Copy the thumbs folder. By default the `thumbs` folder will be copied, and if all images you’re using in your pages go through the `thumb()` helper or `$image->thumb()` method, you’re golden.
24
+
// Should we add the extension to URLs in the HTML?
25
+
'staticbuilder.uglyurls' => false,
45
26
46
-
2. Copy the content folder and use Kirby tags. By default the `content` folder will be copied as well, so that links to `content/1-section/3-page/myfile.pdf` etc. keep working. If you used Kirby tags to embed images and link to page files, you don’t have anything else to do.
27
+
// Files and folders to copy into the static build folder
3. Tell StaticBuilder to copy page files to a folder named after the page: e.g. `section/page/myfile.pdf`.
30
+
// Lets you provide a function for including/excluding pages
31
+
'staticbuilder.filter' => null,
49
32
50
-
The last option will work for relative paths in your HTML (`<a href="myfile.pdf">My File</a>` or `<img src="hello.svg" alt="">`) *only if* the page HTML is written to the same folder. So you probably want to use the `extension` and `withfiles` options together:
51
-
52
-
```php
53
-
c::set([
54
-
'staticbuilder' => true,
55
-
'staticbuilder.extension' => '/index.html',
56
-
'staticbuilder.withfiles' => true
33
+
// Do not copy files from the page's content folder
34
+
'staticbuilder.withfiles' => false
57
35
]);
58
36
```
59
37
60
-
### HTML pages outside of a web site
61
-
62
-
If you need to share the resulting site outside of a web server (on a local network share for documentation, on a thumb drive, distributed as a ZIP file, etc.), you will need fully relative URLs between pages.
63
-
64
-
This can be achieved with this configuration:
65
-
66
-
```php
67
-
c::set([
68
-
'staticbuilder' => true,
69
-
'staticbuilder.baseurl' => './',
70
-
'staticbuilder.uglyurls' => true
71
-
]);
72
-
```
73
-
74
-
In the output, URLs from page A to page B should look like: `./../other-section/page-b.html`.
75
-
76
-
Note that this plugin only rewrites URLs that are generated by Kirby objects or by the `url()` helper function. If you hardcoded some URLs or paths in your templates, they won’t be rewritten.
77
-
78
-
79
38
## Option details
80
39
81
40
### `staticbuilder.outputdir`
82
41
83
-
By default, the static site will be generated in `[yourproject]/static`. You can change this path, providing a relative path (e.g. `../build/static`) or an absolute one (e.g. `/Users/me/Sites/mywebsite/static`).
42
+
The default value, `'static'`, means we will ouptut the static build in `[yourproject]/static`.
84
43
85
-
Two restrictions:
44
+
DANGER: the contents of this folder will be *deleted* before each build! If you choose a different folder name or path, make sure it doesn’t match an existing folder like `kirby`, `site`, `thumbs`, etc.
86
45
87
-
1. PHP and your local web server (Apache/MAMP/WAMP/etc.) must permissions to write to that folder.
88
-
2. The output folder MUST be named `static`, even if you change the path. This restriction helps making sure you don’t kill your system or delete existing files.
46
+
There are a few restrictions in place:
89
47
90
-
WARNING: when building the site, the contents of this folder will be deleted first. You should not change the contents of this folder manually, or you will lose your changes on the next build!
48
+
1. Absolute paths (`/var/www/static` or `C:\static-site`) are forbidden.
49
+
2. PHP and your local web server (Apache/MAMP/WAMP/etc.) must have permissions to write to that folder.
91
50
92
-
### `staticbuilder.assets`
51
+
### `staticbuilder.extension`
93
52
94
-
A list of static files or folders to copy in the `static` directory.
53
+
Extension for pages. Defaults to adding a `/index.html` suffix.
95
54
96
55
```php
97
-
c::set('staticbuilder.assets', [
98
-
// Copy the full 'assets' folder
99
-
'assets',
100
-
// Thumbs too
101
-
'thumbs',
102
-
// Use key=>value syntax to change the destination
103
-
'assets/images/favicon.ico' => 'favicon.ico',
104
-
// Getting a file from outside the main project dir
// Use key=>value syntax to change the destination
111
+
'assets/images/favicon.ico' => 'favicon.ico',
112
+
// Getting a file from outside the main project dir
113
+
'../server/static-htaccess.conf' => '.htaccess'
114
+
]);
160
115
```
161
116
117
+
Note: `*` or other wildcards are not supported. You need explicit paths to existing files or folders.
118
+
162
119
### `staticbuilder.filter`
163
120
164
121
With this option you can provide a PHP callback that gets each Page object as its only parameter, and which should return `true` for pages to build and `false` for pages to exclude.
0 commit comments