1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
---
description: 'Learn how to configure the build output folder for the most
common static site generators'
stage: Create
group: Incubation
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Configure the public files folder **(FREE)**
GitLab Pages requires all files you intend to be available in the published website to
be in a root-level folder called `public`. This page describe how
to set this up for some common static site generators.
## Guide by framework
### Eleventy
For Eleventy, you should either:
1. Add the `--output=public` flag in Eleventy's build commands, for example:
`npx @11ty/eleventy --input=path/to/sourcefiles --output=public`
1. Add the following to your `.eleventy.js` file:
```javascript
// .eleventy.js
module.exports = function(eleventyConfig) {
return {
dir: {
output: "public"
}
}
};
```
### Astro
By default, Astro uses the `public` folder to store static assets. For GitLab Pages,
rename that folder to a collision-free alternative first:
1. In your project directory, run:
```shell
mv public static
```
1. Add the following to your `astro.config.mjs`. This code informs Astro about
our folder name remapping:
```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
// GitLab Pages requires exposed files to be located in a folder called "public".
// So we're instructing Astro to put the static build output in a folder of that name.
outDir: 'public',
// The folder name Astro uses for static files (`public`) is already reserved
// for the build output. So in deviation from the defaults we're using a folder
// called `static` instead.
publicDir: 'static',
});
```
### SvelteKit
NOTE:
GitLab Pages supports only static sites. For SvelteKit,
we recommend using [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites).
When using `adapter-static`, add the following to your `svelte.config.js`:
```javascript
// svelte.config.js
import adapter from '@sveltejs/adapter-static';
export default {
kit: {
adapter: adapter({
pages: 'public'
})
}
};
```
### Next.js
NOTE:
GitLab Pages supports only static sites. For Next.js, we
recommend using Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export)
Use the `-o public` flag after `next export` as the build command, for
example:
```shell
next export -o public
```
### Nuxt.js
NOTE:
GitLab Pages supports only static sites.
1. Add the following to your `nuxt.config.js`:
```javascript
export default {
target: 'static',
generate: {
dir: 'public'
}
}
```
1. Configure your Nuxt.js application for
[Static Site Generation](https://nuxtjs.org/docs/features/deployment-targets#static-hosting).
### Vite
Update your `vite.config.js` to include the following:
```javascript
// vite.config.js
export default {
build: {
outDir: 'public'
}
}
```
### Webpack
Update your `webpack.config.js` to include the following:
```javascript
// webpack.config.js
module.exports = {
output: {
path: __dirname + '/public'
}
};
```
## Should you commit the `public` folder?
Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks
for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. So
If you set up a job that creates the `public` folder before deploy, such as by
running `npm run build`, committing the folder isn't required.
If you prefer to build your site locally, you can commit the `public` folder and
omit the build step during the job, instead.
|