Files and structure

#The layout

A theme is a flat set of files in four folders, plus theme.json at the top. Plangku accepts only these paths. Any other path is refused with the message that it "isn't a theme file path".

theme.json
config/
  settings_schema.json
assets/
  site.css
  hero.jpg
sections/
  promo.plang
  hero.plang
snippets/
  product-card.plang

There are no sub-folders. A file inside sections/ is always sections/<name>.plang.

#File kinds and naming rules

You can rename .plang and .css files in the Explorer. A renamed file stays in the same folder and keeps its type.

#What each file does

#theme.json

Optional. It is informative only.

{
	"name": "Warung Modern",
	"version": "1.0.0",
	"author": "Studio Kopi Jawa"
}

The name is trimmed to 80 characters, the version to 20 and the author to 80. If there is no name, Plangku uses "Theme". The name is shown after you upload a package. theme.json must be valid JSON.

#config/settings_schema.json

The theme settings the owner sees in the Theme tab of the visual editor. See Theme settings.

#assets/*.css

Styles for the whole website. Plangku loads them in name order and scopes every selector to the website, so you write .card, not body .card. You can have up to 12. See Styling.

#sections/*.plang

One section per file: a template, one {% schema %} block and an optional {% style %} block. Each file adds a section the owner can add to pages, or replaces a built-in section. See Sections.

#snippets/*.plang

Reusable markup. Render one with {% render 'product-card', title: 'Nasi Goreng' %}. A snippet cannot have a {% schema %} or {% style %} block. A snippet sees only what you pass to it, plus the globals. See Snippets.

If you name a snippet like one of Plangku's platform snippets (heading, button, image, stars), yours replaces it.

#Limits

Saving is refused when a theme goes over any of these limits.

Images do not count towards the per-file character limit. A theme package has its own, separate limits (see Theme packages).

Inside a schema, there are smaller limits:

Anything over these numbers is dropped silently, so keep within them.

#How a section named like a built-in replaces it

Plangku's own sections have handles such as hero, about, menu and footer. If your file is sections/hero.plang, it replaces the built-in Hero on the whole website. Every Hero section, on every page, renders from your file. You do not add it from the section library, because it is not a new section.

To start from the real thing, use Built-in sections → Customize in the Explorer. It copies the built-in template and writes a full schema, so every setting keeps working. See Sections for which handles can be replaced.

A file with any other name, like promo.plang, is a new section. It shows up under Your theme's sections when the owner adds a section.

#Errors block saving

Plangku builds the whole theme every time you save. If any file has an error, nothing is saved, not even the file that is fine. Fix the errors in the Problems panel and save again. Warnings do not block a save. See Saving, history and publishing.

Typical errors:

• A section file with no {% schema %}.
• Invalid JSON in a schema, theme.json or settings_schema.json.
• {% render 'name' %} for a snippet that does not exist.
• Invalid CSS.
• Putting {% schema %} or {% style %} in a snippet.
• A section file named like a built-in that cannot be replaced.

#Delete and rename

Deleting a file removes it from the draft, and the Explorer asks you to confirm. You can bring it back from History.

• Deleting a file that replaced a built-in section sends that section type back to the built-in look.
• Deleting or renaming a section file that pages already use leaves those sections on the page, pointing at a name that no longer exists. They show nothing until you add the new one.

#Related

• Sections
• Setting types
• Theme packages