frappe-ops-website-deploy

name	frappe-ops-website-deploy
description	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.
license	MIT
compatibility	Claude Code, Claude.ai Projects, Claude API. Frappe v15-v16, ERPNext v15-v16.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Deploy Websites on ERPNext/Frappe

Patterns for deploying static HTML/CSS websites to ERPNext v15/v16 using Web Pages, Page Builder, and the REST API.

---

Critical: ERPNext v16 Does NOT Render main_section

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.

---

Decision Tree

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

---

Step 1: Create the Raw HTML Section Web Template

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:

• The fieldtype must be "Text" — Frappe rejects "Code" for Web Template fields
• Allowed fieldtypes: Attach Image, Check, Data, Int, Link, Select, Small Text, Text, Markdown Editor, Section Break, Column Break, Table Break
• The template uses {{ values.html_content }} (with values. prefix) to access field data

---

Step 2: Create Web Pages with Page Builder

Each 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.

Updating an existing page

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"]

---

Step 3: Configure Website Settings

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"}
  ]
}

head_html: Frappe Wrapper Fixes

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:  ; }
 { :  ; :  ; }

These are the only !important overrides you should use — they target Frappe's own wrapper elements, not your content.

---

CSS Management

The golden rule: keep your mockup CSS intact

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.

Where CSS goes

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

What NOT to do

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.

---

Deploying from HTML Mockups

When converting a static HTML mockup to ERPNext Web Pages, follow this process:

1. Extract the body content

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.

2. Rewrite links

Replace .html file references with Frappe routes:

href="about.html"  →  href="/about"
href="index.html"  →  href="/"

3. Handle images

Local img/ references won't work on ERPNext. Options:

• Upload images via Frappe File Manager and use the returned URL
• Use the File API: POST /api/method/upload_file
• Reference external image URLs

4. Deploy script pattern

See 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
        ...

---

Forum Integration with Frappe Discussions

Frappe has built-in DocTypes for discussions that can be embedded on any Web Page.

Available DocTypes

• Discussion Topic — a thread/topic linked to a reference document
• Discussion Reply — a reply within a topic

Creating a forum 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}"
    }
  ]
}

Discussions Web Template fields

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

Managing topics via API

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"}

---

Authentication

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.

---

Troubleshooting

Page is blank / main_section not rendering

You're hitting the v16 Page Builder issue. Switch to content_type: "Page Builder" with page_blocks. See Step 2.

White bar above content

Frappe's .page-header-wrapper and .page-breadcrumbs add empty space. Hide them via head_html. See Step 3.

Web Template creation fails with fieldtype error

Use "Text" not "Code" for the fieldtype. Frappe Web Templates only allow a subset of fieldtypes.

CSS looks wrong / spacing is off

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.

Grid layouts collapse to single column

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.

Images don't show

Local img/ paths from mockups won't resolve. Upload files to ERPNext or use absolute URLs.