Site folder and front matter reference
The site folder
Section titled “The site folder”- The smallest site is one file,
index.html. It needs no front matter, layout or settings. To make it a site, runws new "Name" --herein its folder. - A page is any
.htmlfile. Its path is its address, without.html:about.htmlis/about, andnews/index.htmlis/news./about/and/about.htmlforward to/about. Having bothnews.htmlandnews/index.htmlstops 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
.wsfolder. In the top folder,AGENTS.md,README.mdand thelocalesfolder, 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.icoor/photos/dock.jpg. - The site’s icon in the browser tab is
favicon.icoin 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.icowith an empty reply, so the tab shows the browser’s own icon. - Special files.
404.htmlis shown for any address with no page. A file named_redirectssets redirects, one per line. The file stays out of the published site. The platform writessitemap.xmlandrobots.txtfor a site on its own domain, and tells search engines to skipsitepeek.page. A file ending in.xmlthat starts with front matter, such asnews.xml, is built with Liquid like a page and served as XML, for news feeds. - Liquid runs in every
.htmlfile, and in.xmlfiles 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
imgtag’ssrcset, 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/, andhreflanglink tags in theheadbetween a page and its translations. It adds the analytics script the owner connected, if any (see 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 afterws 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 namedlocales.
Keep old page links when a site moves
Section titled “Keep old page links when a site moves”-
List the old page URLs from the old site or its sitemap.
-
Create a file called
_redirectsin 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 code301for a permanent redirect. Both paths start with a slash. Leave out the scheme, host and query string. Copy percent codes such as%20as they appear in the old URL./about-us.php /about 301 -
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
Section titled “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. |
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.