Deploy HTML/CSS websites to ERPNext/Frappe (v15/v16) as Web Pages via the REST API. Use this skill whenever a user wants to host a website on ERPNext, deploy HTML mockups to Frappe, create Web Pages programmatically, configure Website Settings, or integrate Frappe's Discussion system as a forum. Also use when the user mentions "website on ERPNext", "Web Page API", "Page Builder", "Web Template", or wants to serve custom HTML from Frappe. Covers: Web Pages with Page Builder, custom Web Templates, Website Settings (navbar, footer), CSS management, Frappe Discussion integration, and deployment scripting.
Patterns for deploying static HTML/CSS websites to ERPNext v15/v16 using Web Pages, Page Builder, and the REST API.
In Frappe v16, the main_section field on a Web Page is stored but not rendered in the browser — even with content_type: "HTML" or dynamic_template: 1. The Page Builder (page_blocks) is the primary rendering mechanism.
You must use page_blocks with a custom Web Template to render HTML content.
What do you need?
├── Deploy HTML pages to ERPNext
│ ├── Step 1: Create "Raw HTML Section" Web Template (one-time)
│ ├── Step 2: Create Web Pages with page_blocks
│ └── Step 3: Configure Website Settings
│
├── Add a forum / discussion system
│ └── Use Frappe's built-in Discussion Topic/Reply + Discussions Web Template
│
├── Manage CSS
│ ├── Per-page CSS → Web Page `css` field
│ ├── Global CSS → Website Settings `head_html`
│ └── WARNING: Never stack !important overrides (see CSS Management)
│
└── Configure navigation
└── Website Settings: top_bar_items, footer_items, brand_html, home_page
This is a one-time setup. The template accepts raw HTML and renders it as-is.
POST /api/resource/Web%20Template
{
"name": "Raw HTML Section",
"type": "Section",
"template": "{{ values.html_content }}",
"fields": [
{
"fieldname": "html_content",
"fieldtype": "Text",
"label": "HTML Content"
}
]
}
Important constraints:
fieldtype must be "Text" — Frappe rejects "Code" for Web Template fieldsAttach Image, Check, Data, Int, Link, Select, Small Text, Text, Markdown Editor, Section Break, Column Break, Table Break{{ values.html_content }} (with values. prefix) to access field dataEach page needs content_type: "Page Builder" and its HTML in page_blocks.
POST /api/resource/Web%20Page
{
"title": "Page Title",
"route": "my-page",
"published": 1,
"show_title": 0,
"full_width": 1,
"content_type": "Page Builder",
"css": "<per-page CSS here>",
"page_blocks": [
{
"web_template": "Raw HTML Section",
"web_template_values": "{\"html_content\": \"<div>Your HTML here</div>\"}"
}
]
}
Critical: web_template_values is a JSON string, not an object. Serialize it with json.dumps() before sending.
PUT /api/resource/Web%20Page/{url_encoded_name}
To find a page by route:
GET /api/resource/Web%20Page?filters=[["route","=","my-page"]]&fields=["name"]
PUT /api/resource/Website%20Settings/Website%20Settings
{
"home_page": "home",
"brand_html": "<span style=\"...\">NL</span> My Brand",
"head_html": "<link href=\"fonts.css\" rel=\"stylesheet\">\n<style>/* global CSS */</style>",
"top_bar_items": [
{"label": "About", "url": "/about", "right": 0}
],
"footer_items": [
{"label": "About", "url": "/about"}
]
}
Frappe wraps page content in several divs that add unwanted whitespace. Add these fixes to head_html:
<style>
.page-header-wrapper { display: none !important; }
.page-breadcrumbs { display: none !important; }
.page-content-wrapper { padding: 0 !important; margin: 0 !important; }
.page_content { padding: 0 !important; margin: 0 !important; }
.webpage-content { padding: 0 !important; margin: 0 !important; }
.web-page-content { padding: 0 !important; margin: 0 !important; max-width: none !important; }
.section.section-padding-top { padding-top: 0 !important; }
.section.section-padding-bottom { padding-bottom: 0 !important; }
.web-template-section { padding: 0 !important; margin: 0 !important; }
main { padding: 0 !important; margin: 0 !important; }
</style>
These are the only !important overrides you should use — they target Frappe's own wrapper elements, not your content.
Use the original mockup CSS in each page's css field. Only add Frappe wrapper fixes in head_html. Do not layer !important overrides on top of your content CSS — this leads to cascading conflicts and unpredictable layouts.
| CSS Type | Where | Field |
|---|---|---|
| Mockup/page CSS | Per Web Page | css |
| Google Fonts, Frappe fixes | Website Settings | head_html |
| CSS variables (:root) | Website Settings | head_html |
Never add broad !important overrides for content elements like .card, section, h2, etc. If spacing looks wrong, the cause is almost always a Frappe wrapper div — fix that specifically rather than overriding all your content styles.
When converting a static HTML mockup to ERPNext Web Pages, follow this process:
Strip everything outside the main content area — typically between </header> and <footer>. Remove the mockup's own nav and footer since Frappe provides its own via Website Settings.
Replace .html file references with Frappe routes:
href="about.html" → href="/about"
href="index.html" → href="/"
Local img/ references won't work on ERPNext. Options:
POST /api/method/upload_fileSee scripts/deploy.py for a complete deployment script. The key pattern:
import requests, json
def deploy_page(title, route, html_content, css):
data = {
"title": title,
"route": route,
"published": 1,
"show_title": 0,
"full_width": 1,
"content_type": "Page Builder",
"css": css,
"page_blocks": [{
"web_template": "Raw HTML Section",
"web_template_values": json.dumps({"html_content": html_content})
}]
}
# Create or update (check 409 conflict for existing pages)
resp = requests.post(f"{BASE_URL}/api/resource/Web%20Page",
headers=HEADERS, json=data)
if resp.status_code == 409:
# Find and update existing
...
Frappe has built-in DocTypes for discussions that can be embedded on any Web Page.
Use the built-in "Discussions" Web Template as a page block:
{
"page_blocks": [
{
"web_template": "Raw HTML Section",
"web_template_values": "{\"html_content\": \"<section><div class=\\\"container\\\"><h1>Forum</h1></div></section>\"}"
},
{
"web_template": "Discussions",
"web_template_values": "{\"title\": \"Discussies\", \"cta_title\": \"Nieuw onderwerp\", \"docname\": \"forum\", \"single_thread\": 0}"
}
]
}
| Field | Type | Purpose |
|---|---|---|
title | Data | Section heading |
cta_title | Data | Button text for new topic |
docname | Link | Web Page to attach discussions to |
single_thread | Check | 0 = multiple topics, 1 = single thread |
POST /api/resource/Discussion%20Topic
{"subject": "My topic", "reference_doctype": "Web Page", "reference_docname": "forum"}
POST /api/resource/Discussion%20Reply
{"topic": "TOPIC0001", "reply": "My reply text"}
All API calls require authentication via token header:
Authorization: token {api_key}:{api_secret}
Generate API keys in ERPNext: User Settings → API Access → Generate Keys.
Never store API keys in skill files, SKILL.md, or commit them to git. Pass them as environment variables or read from a secure config.
You're hitting the v16 Page Builder issue. Switch to content_type: "Page Builder" with page_blocks. See Step 2.
Frappe's .page-header-wrapper and .page-breadcrumbs add empty space. Hide them via head_html. See Step 3.
Use "Text" not "Code" for the fieldtype. Frappe Web Templates only allow a subset of fieldtypes.
Check if Frappe's .section.section-padding-top or .page-content-wrapper are adding padding. Fix those specifically — don't override your content CSS with !important.
If your mockup CSS has media queries that override grid columns, those will apply on ERPNext too. Check the rendered CSS for conflicting media query rules.
Local img/ paths from mockups won't resolve. Upload files to ERPNext or use absolute URLs.