# Site folder and front matter reference

> Which files a site publishes, how a file's path becomes its address, special files, redirects and front matter settings.

## The site folder

- **The smallest site is one file, `index.html`.** It needs no front matter, layout or settings. To make it a site, run `ws new "Name" --here` in its folder.
- **A page** is any `.html` file. Its path is its address, without `.html`: `about.html` is `/about`, and `news/index.html` is `/news`. `/about/` and `/about.html` forward to `/about`. Having both `news.html` and `news/index.html` stops the build.
- **Not published:** any file or folder whose name starts with an underscore or a dot, at any depth. The layouts, includes and data folders are each named with an underscore first, so none of them is published. Neither is a drafts folder of your own named the same way, nor the `.ws` folder. In the top folder, `AGENTS.md`, `README.md` and the `locales` folder, which holds the site's strings in each language (short texts such as headings and labels), are not published either.
- **Any other file** is published at its own path, such as `/styles.css`, `/favicon.ico` or `/photos/dock.jpg`.
- **The site's icon** in the browser tab is `favicon.ico` in the top folder, or any image the layout names with `<link rel="icon" href="/icon.svg">`. A site without one answers browsers' request for `/favicon.ico` with an empty reply, so the tab shows the browser's own icon.
- **Special files.** `404.html` is shown for any address with no page. A file named `_redirects` sets redirects, one per line. The file stays out of the published site. The platform writes `sitemap.xml` and `robots.txt` for a site on its own domain, and tells search engines to skip `sitepeek.page`. A file ending in `.xml` that starts with front matter, such as `news.xml`, is built with Liquid like a page and served as XML, for news feeds.
- **Liquid runs in every `.html` file,** and in `.xml` files with front matter. Plain HTML with no Liquid tags comes out as written. Liquid does not run in CSS or JavaScript files. `{% raw %}` and `{% endraw %}` keep a block, such as a script that uses curly braces, from being read as Liquid.
- **What the platform changes in a page:** it lists smaller copies of each photo in its `img` tag's `srcset`, so phones load a smaller one. It adds hidden fields for spam and required-field checks, and a thank-you note to forms that post to `/_ws/forms/`, and `hreflang` link tags in the `head` between a page and its translations. It adds the analytics script the owner connected, if any (see [Analytics](https://docs.websitestrategy.com/reference/forms/#analytics)). On its own domain, each page has one canonical URL in the response header. The platform removes any canonical link from the public HTML. On previews only, it adds a small script that updates open pages after `ws preview`. When the owner of a bought site opens the page to point at part of it, the platform adds a number to each element and one small script, so it can tell which part was pointed at.
- **Reserved:** addresses starting with `/_ws/` belong to the platform, and so does the top folder named `locales`.

### Keep old page links when a site moves

1. List the old page URLs from the old site or its sitemap.
2. Create a file called `_redirects` in the new site's source folder. Add one line for each old path that changed. A line has three parts in this order: the old path, the new page path and the status code `301` for a permanent redirect. Both paths start with a slash. Leave out the scheme, host and query string. Copy percent codes such as `%20` as they appear in the old URL.

   ```text
   /about-us.php /about 301
   ```

3. Publish. Once the old domain points to the new site, open the old URLs on that domain. Each one should take you to its new page. The sitemap lists the new page URLs.


## Front matter

Front matter is the block of settings between two `---` lines at the top of a page. Liquid runs in its text values. A value can also be a list or a map, as `addresses:` and `languages:` are below.

| Setting | What it does |
|---|---|
| `layout: default` | Wraps the page in `_layouts/default.html`. |
| `title: About` | The page's title, read as `page.title`. To give it in each language, print a string with `t` in the value, as under [Languages](https://docs.websitestrategy.com/reference/languages/#languages). |
| `each: news` | Makes one page per record in a list in `data`, such as `data.news` or `data.menu.cakes`. The file name, such as `[slug].html`, names the field that sets each page's address. |
| `addresses: { fr: /fr/a-propos }` | The page's address in another language. Without it, the address is the language's code, then the main address: `/fr/about`. On an `each:` page the bracketed field is filled in per language: `{ fr: /fr/nouvelles/[slug] }`. |
| `languages: [fr]` | The page is only in these languages and needs no translation. |

Any other setting, such as `hero_photo: /photos/dock.jpg`, is the page's own, read as `page.hero_photo`.

