docs

Concepts

Project structure

What's inside a Div project and what each piece is for.

Project structure

A Div project is a folder. There's one required file (the manifest), but a useful website also has at least one HTML entry point.

After div new mysite, the layout is gloriously minimal:

mysite/
├── .divignore
├── div.json
└── index.html

You add files. Whatever's in the folder (minus ignored files) gets uploaded on div deploy and served at <slug>.div.so. That's the whole mental model.

#The files Div knows about

#div.json

The project manifest. Created by div new, updated by div deploy.

{
  "slug": "mysite-a4f9d2",
  "createdWith": "div@3.0.2"
}
  • slug — null until first deploy. Once set, the CLI uses it to recognize the folder as an existing project.
  • createdWith — version of Div that scaffolded the project (e.g. div@3.0.2). Informational only.

div.json is not uploaded to the server. It's a local checkout marker. Commit it to git so collaborators (and future-you on a new machine) know the slug.

See the div.json reference for the full schema.

#.divignore

Created by div new as a commented template you can extend. A list of paths to keep out of div deploy, using gitignore syntax.

# never upload draft posts
drafts/
*.draft.html

# or screenshots from your design tool
*.sketch
*.fig

Built-in defaults (applied even with no .divignore):

node_modules
.git
.DS_Store
.env*
div.json
*.log

See the .divignore page for full syntax.

#index.html

The default entry point. When someone visits <slug>.div.so/, this is what they get.

You can have many HTML files. Each path corresponds to a URL — about.html is at <slug>.div.so/about.html, blog/post-1.html is at <slug>.div.so/blog/post-1.html. Simple, predictable, no surprises.

#Anything else

CSS, JavaScript, images, fonts, JSON, PDFs — all uploaded as-is and served verbatim. There's no build step and no asset pipeline. <link rel="stylesheet" href="styles.css"> works because styles.css is a file in the folder. You know — the way the web was originally meant to work.

#Optional: the src/ folder

If you create a folder called src/ inside your project, Div quietly switches into a small static-site-generator mode. src/ becomes the editable source; the published root is auto-generated from it.

The minimal SSG layout is just two files:

mysite/
├── div.json
└── src/
    ├── data.json
    └── index.html

In src/data.json:

{
  "site_name": "My Cool Site",
  "year": "2026"
}

In src/index.html:

<!doctype html>
<title>{site_name}</title>
<p>Made in {year}.</p>

When you save, Div substitutes {site_name} and {year} and writes the rendered HTML to mysite/index.html. That's the file that gets served.

The full template-variables system is documented in Template variables.

You don't have to use src/. The CLI detects it automatically — as soon as the folder has any content under src/, every save flips to SSG mode.

#What gets deployed

Everything in your folder, except:

  • Files matched by built-in ignores (node_modules, .git, etc.).
  • Files matched by your .divignore.
  • div.json itself.
  • Files larger than 10 MB (the deploy errors out before any upload starts; see Limits).
  • Files whose extension isn't on the allowlist — archives, executables, source files for non-web languages, etc.

In SSG mode, only the rendered output (the project root) is published; the src/ directory itself is editable but not exposed. (More precisely: src/ is uploaded to S3 alongside the rendered output, but the preview host serves from the root, so visitors see the rendered files.)

#See also