How a site is laid out

A site is a folder. Taragen walks it with a few simple rules:

- Files and folders whose names start with `.` are ignored.
- Files and folders whose names start with `_` are special: they are never
  pages and are never copied as-is (with the exception of the root `_assets/`
  folder). This is where layouts, partials, globals, defaults, output templates,
  and assets live.
- Files ending in `.jsx`, `.md`, or `.tmpl` are **page sources**.
- Folders are pages too (see [Folders as pages](#folders-as-pages)).
- Everything else is a **static file** and is copied to the same path in the
  output.

A path segment written as `[name]` is a page template parameter; see
[Generated pages](/docs/manual/generated-pages).

## Special files

| File | Purpose |
| --- | --- |
| `_layout.jsx` / `_layout.tmpl` | Wraps every page in its folder and below. See [Layouts](/docs/manual/layouts). |
| `_globals.jsx` | Values and helper functions available to all JSX in its folder and below. See [Defaults and globals](/docs/manual/defaults-and-globals). |
| `_defaults.jsx` | Default page data for pages in its folder and below. |
| `_outputs/<name>.jsx` | An extra output for every HTML page in its folder and below, such as a `.txt` version or a share card. See [Extra outputs per page](/docs/manual/extra-outputs-per-page). |
| Any other `_name.jsx` / `_name.tmpl` | A partial, included with `partial("_dir/name")`. See [Partials](/docs/manual/partials). |
| `_assets/` (root only) | Copied verbatim to `_public/_assets/`, never rendered. |
| `_redirects` (root only) | Redirect rules in Netlify's format. See [Aliases and redirects](/docs/manual/aliases-and-redirects). |

A typical site looks like this:

```
mysite/
├── _assets/
│   ├── fonts/Recursive.woff2
│   └── style.css
├── _globals.jsx
├── _defaults.jsx
├── _layout.jsx
├── _outputs/
│   ├── txt.jsx
│   └── card.png.jsx
├── _partials/
│   └── footer.jsx
├── _redirects
├── index.jsx
├── about.md
├── articles/
│   ├── _layout.jsx
│   ├── index.jsx
│   ├── feed.xml.jsx
│   └── 2021/
│       └── ngrok.md
└── tags/
    └── [tag].jsx
```

## Page paths and URLs

A page's URL comes from its file path: strip the extension, strip a trailing
`/index`, and the root becomes `/`.

| Source | URL | Built file |
| --- | --- | --- |
| `index.jsx` | `/` | `_public/index.html` |
| `about.md` | `/about` | `_public/about/index.html` |
| `about/index.jsx` | `/about` | `_public/about/index.html` |
| `articles/2021/ngrok.md` | `/articles/2021/ngrok` | `_public/articles/2021/ngrok/index.html` |
| `articles/feed.xml.jsx` | `/articles/feed.xml` | `_public/articles/feed.xml` |

Pages without an extension get clean URLs: they're written as
`<path>/index.html`. A page whose name keeps an extension after the format
extension, like `feed.xml.jsx`, is written as-is.

`about.jsx` and `about/index.jsx` are the same page. Use the folder form when a
page has files of its own, like images, next to it. Blog posts are just pages,
and a post with several images or downloads reads well as a folder:

```
articles/2021/ngrok/
├── index.md          the post, at /articles/2021/ngrok
├── diagram.png       linked from the post as diagram.png
└── tunnel.go
```

## Folders as pages

Every folder is a page node, even without an index file. A folder with no index
file has no source and isn't built, but it still groups its children, so
`pages("articles")` lists everything in `articles/`, and `year.subpages` works
for a `2021/` folder with no index. These source-less nodes are called
**grouping nodes** in this manual.