What is Developer Mode?
Developer Mode is a feature exclusive to Squarespace 7.0 that gives you direct access to the template files powering your site. Instead of working through the visual editor and drag-and-drop interface, you edit raw HTML, LESS, JavaScript, and JSON configuration files through a Git-based workflow.
When enabled, Squarespace creates a Git repository for your site. You clone it, edit locally, push changes, and Squarespace pulls and compiles them automatically. Your template files become the source of truth, not the CMS.
This is for developers who want full control over their markup, styles, and page structure. If you are comfortable with HTML, CSS, and Git, Developer Mode lets you bypass the limitations of the visual editor entirely.
Important
Developer Mode is only available on Squarespace 7.0. It does not exist on Squarespace 7.1. If your site uses 7.1, you are limited to Code Injection and CSS overrides. There is no way to upgrade a 7.0 site to 7.1 or vice versa.
Prerequisites
Before you begin, make sure you have:
- A Squarespace Business or Commerce plan. Developer Mode is not available on Personal plans.
- A GitHub account. Squarespace uses GitHub as its Git provider for Dev Mode.
- Git installed locally so you can clone, edit, and push changes from your machine.
- A code editor (VS Code, Cursor, or similar).
- Basic familiarity with HTML, CSS, and the command line.
Warning
Enabling Developer Mode is a one-way action on a given site. Once enabled, you cannot disable it. The visual template switcher also becomes unavailable. Make sure you are committed to a code-based workflow before enabling it.
Step 1: Enable Developer Mode
In the Squarespace admin panel, navigate to:
Settings → Advanced → Developer Mode
Toggle Developer Mode on. Squarespace will warn you that this is irreversible. Confirm, and the platform will initialize a Git repository connected to your site.
After enabling, you will see a prompt to connect a GitHub account. This is the only Git provider Squarespace supports for Dev Mode.
Step 2: Connect Your GitHub Repository
Squarespace will ask you to authorize access to your GitHub account. Once connected, it creates a new repository (or lets you select an existing one) and pushes the current template files into it.
Clone the repository to your local machine:
git clone git@github.com:YourOrg/your-site-repo.git cd your-site-repo
You now have a local copy of every file that defines your site's template. Changes you push to the main branch are automatically pulled by Squarespace and deployed live.
Tip
Squarespace watches the default branch (usually main or master). Pushing to any other branch has no effect on the live site. Use feature branches during development and merge to main when ready to deploy.
Step 3: Understanding the File Structure
Once cloned, your repository contains these key files and directories:
your-site-repo/
template.conf # Template configuration (name, stylesheets, layouts)
site.region # Global HTML shell (header, footer, meta tags)
pages/
home.page # Page content (partial HTML)
home.conf # Page meta (title, description)
about.page
about.conf
styles/
base.less # Global styles, design tokens, keyframes
home.less # Page-specific styles
scripts/
site.js # Global JavaScript
assets/ # Static files (images, fonts, SVGs)template.conf
The root configuration file. It tells Squarespace the template name, which LESS files to compile, and how layouts and navigation are structured.
{
"name": "My Custom Template",
"author": "Your Name",
"layouts": {
"default": {
"name": "Default",
"regions": ["site"]
}
},
"navigations": [
{ "title": "Main Navigation", "name": "mainNav" }
],
"stylesheets": [
"base.less",
"home.less"
]
}Key detail
The stylesheetsarray is the only way to get LESS files compiled. Each file listed here is compiled independently by Squarespace's LESS compiler. @import statements inside LESS files do not work.
site.region
This is the global HTML shell that wraps every page on your site. It contains the <head> section, header navigation, footer, and two critical Squarespace tags:
{squarespace-headers}— injects the compiled CSS from your LESS files and minimal platform JavaScript into the<head>. Remove this and your styles stop loading.{squarespace.main-content}— the injection point where your.pagefile content renders.
pages/ directory
Each page consists of two files: a .page file containing the partial HTML content, and a .conffile containing the page title and meta description. These are not full HTML documents — they are fragments injected into site.region.
styles/ directory
LESS files that compile into your site's CSS. Typically you have a base.less for global styles and design tokens, plus per-page files scoped under page-specific classes.
scripts/ directory
JavaScript files. The main entry point is usually site.js, loaded via a <squarespace:script> tag in site.region.
Step 4: Making Your First Edit
Start with something simple. Open styles/base.less and add a CSS custom property:
:root {
--color-brand: #1a1a1a;
}
body {
font-family: 'Inter', -apple-system, sans-serif;
color: var(--color-brand);
margin: 0;
padding: 0;
}Then open a page file, for example pages/home.page, and add some content:
<div class="ldp-service-page ldp-page-home">
<section class="hero">
<h1>Welcome to our site.</h1>
<p>Built with Developer Mode.</p>
</section>
</div>Save the files, commit, and push:
git add . git commit -m "Add initial styles and homepage content" git push origin main
Step 5: Understanding the Deploy Process
Squarespace continuously watches your repository's default branch. When you push a commit:
- Squarespace pulls the latest changes from GitHub.
- LESS files listed in
template.confare compiled into CSS. - JavaScript files are bundled.
- Template and page configuration files are parsed.
- The live site updates within seconds.
There is no build step on your end. No CI/CD pipeline to configure. Push to main, and the site updates. This simplicity is one of Dev Mode's strengths, but it also means a broken push goes live immediately.
Warning
If you push a LESS file with a syntax error, all of your custom CSS will fail silently. The site will render with no styles. Always check site.css?minify=false after deploying to verify your styles compiled correctly. LESS errors appear at the bottom of that file.
Tip
Use feature branches during development. Only merge to main when you have verified your changes locally. Since there is no staging environment, your main branch is production.
Common Pitfalls
1. Using @import in LESS files
Squarespace's LESS compiler does not support @import. If you try to import one LESS file into another, the import is silently ignored. Instead, list every LESS file in the template.conf stylesheets array. Each file compiles independently.
2. Adding full HTML document tags in .page files
Page files are fragments, not full documents. Do not include <!doctype>, <html>, <head>, or <body> tags. These are already provided by site.region. Adding them creates invalid nested HTML.
3. One undefined LESS variable breaks everything
If any LESS file references a variable that does not exist, the entire LESS compilation fails silently. You get zero custom CSS. This is the most common and most frustrating Dev Mode bug. Always test after adding new variables.
4. Forgetting to add LESS files to template.conf
Creating a new .less file is not enough. If it is not listed in the stylesheets array of template.conf, Squarespace will never compile it. Your styles simply will not exist.
5. Expecting squarespace-headers to be a content hook
{squarespace-headers} is the CSS delivery pipe. It injects your compiled LESS into the page head. It is not a place to inject custom content. If you remove it, all your styles disappear.