Guide 00 · Developer docs

Core dna for site builders

Read this guide first. Core dna is hosted, so there is nothing to install; your repository holds only templates and front-end assets; and a new kind of page starts in the admin, with a layout. In half a day, from what the platform is to a page you built, deployed and rendered in Smarty or Twig.

L0 Start reading

5

units

28

pages

Who this is for. Everyone starting on a Core dna site, whatever their role: theme developer, JavaScript developer, content modeller, integrations engineer or site operator. It assumes you know HTML, CSS, git and a command line, and nothing about Core dna. Every later guide assumes you have read it.

Three assumptions it corrects

That you will run the application on your own machine. You will not: the platform is hosted, and you work against a development environment that Core dna runs for the site.
That the repository contains the application. It holds the site's templates and front-end assets. Content, layouts, settings and users live in the platform's database.
That building a page starts with writing a template. It starts with a layout in the admin. A template that no layout points at is never rendered.

The order of the units

What you are building on explains the platform, its two ways of building a site, its two template engines and its vocabulary. From zero to a deployed change gets you access, a working build and a first deploy. Your first page, end to end builds one page type in the platform's real order, with the template in both engines. From URL to rendered page follows a request to your template and lists what every template receives. Choosing what to read next sends you on, with the house rules every theme follows.

Read the units in order. The first page of the third unit is where you start building, and the pages before it are what make the building make sense.

Contents

5 units, in reading order.

What you are building on

What Core dna is, the two ways to build a site on it, its two template engines, the words every other page uses, the URLs a site answers on, where your repository ends and the platform begins, and why development starts with a layout. Read it before writing any code. 7 pages

Core dna in one page Core dna is a hosted platform: one codebase, run by Core dna, serves every customer's sites from the customer's own database. There is nothing to install or run on your machine. You work with an admin, a theme repository, two APIs, custom endpoints and an MCP server. Read more Two ways to build a site The pages of a Core dna site are composed in one of two places: on the platform, from your Smarty or Twig templates, or in an application of your own, from the APIs. Most sites are rendered on the server with a few parts filled in by the browser. Decide which before you write anything. Read more Smarty and Twig are peers Core dna renders server-side templates in Smarty or Twig. Each site uses one, and both receive the same variables and the same records under the same names. What is the same, the handful of differences, and why every template example in these docs is given in both. Read more The vocabulary every page assumes The terms every other page in these docs uses without explaining them: client, site, environment, hostname, record, layout, layout area, input type, component, custom entity, abstraction, member and backend user, and job. One paragraph each, with where each is covered in depth. Read more The URL surfaces of a site Every Core dna site answers on the same paths: the public site at /, the admin at /cdna-admin, the REST API at /cdna-api, GraphQL at /cdna-api/graphql, custom endpoints at /cdna-api/webhook and the MCP server at /cdna-mcp. A real request to each, and what each answers when something is wrong. Read more What is yours and what is the platform's Your repository holds templates and front-end assets. The platform holds everything else: content, layouts, input types, users, settings, jobs and media. Where each part of a site lives, how it is changed, and whether a git push carries it. Read more Development starts with a layout A template that no layout points at is never rendered, and a layout can only point at a file already on the server. So a new kind of page starts with a layout planned for the admin and a placeholder template, not finished markup. The rule, the order of the work, and what it changes in a plan. Read more

From zero to a deployed change

From nothing to a change deployed on a development site: the access to ask for, the template engine, the repository's shape, the build and its committed output, deploying by branch, and connecting your editor to the site's MCP server. For a developer's first day on a site. 7 pages

The access to ask for Four things to ask for on your first day, and who usually grants each: a backend user on the development site, its hostname, the theme repository with its branch mapping, and the project's issue tracker. A request you can send once instead of four times. Read more Which engine a site uses Before you read or copy any template, find out whether the site renders in Smarty or Twig. The thirty-second check is the tags in any file under templates/; the setting behind them is Globals.template.engine. Why it matters, and where to look when a copied example fails. Read more The shape of a theme repo A theme repository holds templates, front-end source, the built files the site serves, and a few files served as they are. What each folder is for, which ones are generated, what the platform does with each, and how to read a repository you have not met. Read more Finding and running the build Core dna sites build their front end with webpack or with gulp, and the repository says which. How to tell in a minute from package.json and the build configuration, the commands to run, and why you run the production build once before changing anything. Read more The build output is committed and served The platform compiles nothing when you deploy: a site serves its built CSS and JavaScript exactly as committed. So you build before you push, never edit the built files, settle their merge conflicts by building again, and give every asset URL a cache-buster. Read more Deploying a change Deploying is pushing a branch. Every environment that follows that repository and branch makes its files match the branch and clears its caches. How branches map to environments, how to see what is deployed, and what to do when you push the wrong thing. Read more Connecting your editor to the MCP server Every site has an MCP server at /cdna-mcp, through which an AI assistant in your editor reads and changes the site's content and structure, acting as you. A .mcp.json with a development and a production entry, what the first connection does, and what to do if it fails. Read more

Your first page, end to end

One page type built from nothing, in the order the platform needs: a placeholder template, a layout pointing at it, its areas, a published page, and the template that renders the areas in Smarty and Twig. Then the four checks for when a change does not show. 6 pages

Start with a placeholder template The first page of a site, built in the order the platform needs, and its first step: a placeholder template at the path the layout will name, committed and deployed. Then what a wrong template path looks like in each engine. Read more Create the layout In the admin, under Customization › Layouts, add a layout for the template you deployed: its name, its template, and the controller that makes it a page layout. Each field of the form, the controllers you can choose from, and what to check when the layout does not appear where you expect. Read more Add the areas and their input types A layout's areas are the fields editors fill in. Give the article a heading, a body and an image, each with a name, an input type, a label and help for the editor. Why the name is the field to get right, what the other settings do, and what to do when no input type fits. Read more Create and publish a page Add a page under Content › Pages, choose the Article layout, fill in the fields your areas produced, and publish it. Then check it signed out, because a backend user sees unpublished pages that visitors get a 404 for. Read more Render the areas in both engines Replace the placeholder with markup that reads the areas: getAreaText() for plain text, getAreaHtml() for rich text, getAreaImage() for an image. The template in Smarty and in Twig, what each call returns when a field is empty or a name is wrong, and how to see the result. Read more Nothing changed: the four checks You changed something and the page looks the same. Four checks, in the order that finds the cause fastest: did you build, did you deploy, is it cached, and is the record published while you look signed out. Then what to check when all four pass. Read more

From URL to rendered page

The path from a hostname to rendered HTML, at the depth a site builder needs: hostname to site, path to the API, admin or public site, module route to controller, and the record's layout to the template. Then the variables every template receives, and how to inspect a render. 5 pages

Hostname to site, prefix to abstraction The path from a URL to your HTML and its first steps: the hostname picks the environment, site and client, and the start of the path picks the API, the admin or the public site, where the page cache is checked before any template runs. Where to look when a hostname reaches the wrong site. Read more Module route to controller On the public site, the start of the path picks a module and the module's own routes pick a controller; anything no module claims goes to Pages. Why a site builder almost never writes a route, the exceptions, and the one place a URL maps straight to a template. Read more The layout chooses the template The controller finds the record; the record's layout names the template. One controller renders every page of a site, each with its own layout's template, and a page with no layout falls back to the module's default template. Shown on this documentation site's own pages. Read more The variables in every template The platform variables every template receives, under the same names in Smarty ($_url) and Twig (_url): what each is for, which exist only on the public site, and which only when someone is signed in. Then the variables a controller adds, such as page and record. Read more Inspecting a render How to see what a template received and why a page came out wrong: debug_vars in both engines on a development environment, the error page and the admin's Template Errors list, and what the usual surprises, from Template not found to a blank space, mean. Read more

Choosing what to read next

Where to go after this guide: the twelve guides and the three that are required, how to find an answer in these docs, and the house rules every theme follows, stated once. Short and navigational; its job is routing, not teaching. 3 pages

The twelve guides The twelve Developer Guides after this one, a line each on who it is for and when to read it. Three are required whatever you build: Choosing how to build, the template languages, and input types, layouts, components and images. Why those three. Read more Finding your way around these docs These docs hold four kinds of page: guides read in order, how-tos for one task, troubleshooting answers for one symptom, and reference generated from the platform. Which to reach for, what the depth levels mean, how the how-to topics and search work, and why there is no filter by template engine. Read more Conventions every theme follows The house rules for every Core dna theme, stated once so no later page repeats them: BEM class names in SCSS, a bundle per page type, a nonce on every script tag, a cache-buster on every asset URL, no secrets in tracked files, escaped output, and links built from route names. Read more