# The starter files ws new writes

> Every file ws new writes into a new site's folder, as it writes it.

A new site's folder holds these files, exactly as `ws new` writes them. `ws` also writes `.gitignore`, and keeps the site's ID in `.ws/`.

## index.html

```html title="index.html"
---
layout: default
title: Home
---
<h1>{{ site.name }}</h1>
<p>Welcome. This page is index.html.</p>
```

## _layouts/default.html

```html title="_layouts/default.html"
<!doctype html>
<html lang="{{ page.lang }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ page.title }} · {{ site.name }}</title>
  <link rel="stylesheet" href="/styles.css">
</head>
<body>
  {% render 'header.html' %}
  <main>{{ content }}</main>
  {% render 'footer.html' %}
</body>
</html>
```

## _includes/header.html

```html title="_includes/header.html"
<header>
  <a href="/" class="name">{{ site.name }}</a>
  <nav>
    <a href="/">Home</a>
  </nav>
</header>
```

## _includes/footer.html

```html title="_includes/footer.html"
<footer>
  <p>© {{ "now" | date: "%Y" }} {{ site.name }}</p>
</footer>
```

## styles.css

```css title="styles.css"
:root { --ink: #1d2733; --paper: #fbfaf7; --accent: #0f6e8c; }
body { margin: 0; font: 18px/1.55 system-ui, sans-serif; color: var(--ink); background: var(--paper); }
header, main, footer { max-width: 60rem; margin: 0 auto; padding: 1rem; }
img, video { max-width: 100%; height: auto; }
header { display: flex; justify-content: space-between; align-items: center; }
a { color: var(--accent); }
```

## AGENTS.md

```markdown title="AGENTS.md"
# This folder is a Website Strategy site

Write pages in plain HTML, CSS and JavaScript. The platform builds and hosts them.

- A page is an `.html` file. Its path is its address: `about.html` is `/about`, `news/index.html` is `/news`. `/about/` redirects to `/about`.
- Every file is published at its own path (`/styles.css`, `/photos/dock.jpg`), except files and folders whose names start with `_` or `.`, at any depth: `_layouts` (page wrappers), `_includes` (shared parts), `_data` (data), `_redirects`, `.ws`. `AGENTS.md`, `README.md` and `locales/` here are not published.
- Front matter (YAML between `---` lines at the top) sets `layout`, `title` and any value you read as `page.NAME`. Front matter is optional; a page with no Liquid tags is served as written.
- Liquid (LiquidJS) runs in every `.html` file, and in `.xml` files with front matter (feeds). A name the platform does not know (a typo such as `site.titel`) or an unknown filter stops the build with the file, line and a fix.
- `{{ }}` prints text: HTML in data, front matter, translations or live data is shown as characters, never run. `| json` prints unescaped only inside a `type="application/json"` script block; elsewhere it is escaped like any value. Only `content`, `{% render %}`, `{% live %}`, `{% text %}` and `| markdown` print HTML; `markdown` and `text` drop scripts, `style` tags, `on...` attributes and unsafe links. There is no `raw` filter. `{{ }}` is refused inside `script` tags (except a `type="application/json"` block holding one `{{ value | json }}`), `on...` attributes, `style` tags and `style` attributes; give data to a script with `<script type="application/json">{{ value | json }}</script>` or a `data-` attribute, and style from data with a class. Links printed into `href`, `src` or `action` must start with `https:`, `http:`, `mailto:`, `tel:`, `/` or `#`.
- `site.name` (the display name) and `site.address` come from the platform; `ws site` shows them. `site.address` has no `/` at the end, so `{{ site.address }}{{ post.url }}` is a full address (feeds need one); previews have it before the first publish. `page.lang` is the language the page is being built in.
- Shared parts: `{% render 'header.html' %}` reads `_includes/header.html`. Includes see `site`, `page` and `data`; pass anything else by name: `{% render 'card.html', title: "Hi" %}`.
- Data: `_data/hours.yml` (or `.json`) is `data.hours`; YAML lists and maps keep their order. Put facts that change (hours, phone, prices) in data files, not in page HTML. A folder `_data/news/` of `.md` files with front matter is the list `data.news`; each file's text is `body`, and `url` is the address of the page an `each:` file makes for it. Name data files and folders with lowercase letters, numbers and underscores. Quote prices in YAML: `price: "$1.79"`.
- Every data folder has a schema, `_data/news.schema.yml` for `_data/news/`, listing each field's kind (`text`, `markdown`, `date`, `number`, `price`, `link`, `image`, `slug`, `yes-no`), `optional: true` and `translate: true`. `ws` writes it from the first record; to add a field, add it to the schema first. A folder of `.md` files lists `body: { kind: markdown, translate: true }`, the text below the front matter. `ws push` refuses a record that does not match. An optional field missing from a record is empty: `{% if post.photo %}` skips it.
- One page per record: `news/[slug].html` with `each: news` in its front matter; the record is `item`. `each:` takes any list in `data` (a folder, a YAML list, or `menu.cakes`). The bracketed field's values must be lowercase letters, numbers and hyphens, present and unique.
- Live data: the one source is `weather` (Environment Canada). `{% live 'weather' %}...{{ live.item.temperature }}...{% for p in live.items %}{{ p.name }}: {{ p.summary }}{% endfor %}...{{ live.credit }}{% fallback %}...{% endlive %}`. `live.item` is current weather (`temperature`, `wind`, `humidity`, `updated`); `live.items` is the forecast (`name`, `summary`, `temperature`, `text`). Always keep `live.credit` and a fallback. `ws sources connect weather "Town NS"` links it.
- Forms: `<form method="post" action="/_ws/forms/NAME">` is captured by the platform; any other form is left alone. NAME is any lowercase name with hyphens; nothing to register. Reserved field names: `email` (reply-to), `thanks` (page shown after sending, such as `<input type="hidden" name="thanks" value="/thank-you">`), anything starting with `_ws`. Entries are saved, then emailed to the owner (to the builder before purchase; to you only, on a preview). No JavaScript needed.
- The server enforces `required` on the form it served, including required consent checkboxes. JavaScript can fill a value before sending. If JavaScript may disable a required control, add `data-ws-may-disable` on that control. Browsers omit disabled controls, so the server skips its requirement.
- Scripts and style sheets may load from this site, `/_ws/lib/` (`ws libraries` lists them) or any `https` domain; `ws push` lists their outside domains. Inline scripts, module scripts and import maps are fine. Images, fonts, video, fetch and iframes may use any https address. Do not block framing: the owner's tools show the site in a frame.
- Add no analytics or tracking tags. Page views are counted by the platform; the owner connects Google Analytics 4 or PostHog in their account, and the platform adds the script.
- Wrap code that uses `{{` or `{%` (shaders, templates) in `{% raw %}...{% endraw %}`.
- Languages: the site has every language of the business's current site (`ws site --languages en,fr`; first is main). Write each page once; it is built in every language, at `/fr/about` for French, or the address front matter gives with `addresses: { fr: /fr/a-propos }`. Strings (headings, labels, buttons) go in `locales/en.json`, `locales/fr.json` as nested JSON, `{ "menu": { "about": "About" } }` (a flat `"menu.about"` key is not read), and print with `{{ 'menu.about' | t }}`; link to another page with `{{ '/about' | lang_path }}`. Longer writing goes in `{% text %}English Markdown{% in 'fr' %}French Markdown{% endtext %}`. French data goes in `_data/fr/` with the same file names, holding only the fields the schema marks `translate: true` and the `body`. Only records in data folders are translated: a single file such as `_data/officers.yml` is not, so make it a folder with a schema, or keep its words in locales. `page.translations` lists the page in other languages (`lang`, `name`, `path`). Translate in the same change as the main language: `ws push` refuses a missing `t` name, a `text` block without every language, or a record without its translated fields. A page for one language only sets `languages: [fr]`. Never replace a translation the owner corrected; `ws push` refuses and names it.
- Every change publishes once the automatic checks pass. `ws push --needs-approval` sends one change to the owner instead; on a site set with `ws site --approval required`, every change waits for the owner.
- `404.html` is the not-found page. `_redirects` holds lines like `/old /new 301`.
- `/_ws/` belongs to the platform. Do not create a `_ws` folder.

Commands: `ws preview` (private link, and a QR code in a terminal), `ws preview --watch` (updates open pages as you save), `ws push` (commit first; the commit message is the version note), `git pull`, `ws status`, `ws site` (settings; a change makes a version). Add `--json` for output you can parse. Run `git pull` before you start. If `ws push` says someone published first, run `git pull`, resolve any conflict Git reports (`ws push` refuses a file with conflict markers left in it), commit, and push again.
```
