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.tmplare page sources. - Folders are pages too (see 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.
Special files
| File | Purpose |
|---|---|
_layout.jsx / _layout.tmpl |
Wraps every page in its folder and below. See Layouts. |
_globals.jsx |
Values and helper functions available to all JSX in its folder and below. See 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
.
|
Any other _name.jsx / _name.tmpl |
A partial, included with partial("_dir/name"). See Partials. |
_assets/ (root only) |
Copied verbatim to _public/_assets/, never rendered. |
_redirects (root only) |
Redirect rules in Netlify's format. See 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.
