Frappe_Claude_Skill_Package frappe-ops-website-deploy

install

source · Clone the upstream repo

git clone https://github.com/OpenAEC-Foundation/Frappe_Claude_Skill_Package

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/OpenAEC-Foundation/Frappe_Claude_Skill_Package "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/source/ops/frappe-ops-website-deploy" ~/.claude/skills/openaec-foundation-frappe-claude-skill-package-frappe-ops-website-deploy && rm -rf "$T"

manifest: skills/source/ops/frappe-ops-website-deploy/SKILL.md

source content

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"

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

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

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