Mini-sites — Developer Reference

Model hierarchy

Website (owner FK → User)
  ├── WebsiteSection        (sort_order)
  │     └── SectionAsset   (parent_page FK self, depth limit 4)
  │           └── PageBlock (block_type CharField, content JSONField, sort_order)
  ├── WebsiteLogo           (image, sort_order, is_active)
  └── WebsiteRevision       (snapshot JSONField, note, created_at)

ContactMessage  (website FK)
SectionAssetLog (asset FK, user FK, status, message, filename, created_at)

Key Website model fields

• slug — internal slug, scoped per owner (not globally unique)
• public_slug — globally unique, required for publishing; cleared to unpublish
• is_published (bool) + publish_visibility (PUBLIC/UNLISTED/GROUP)
• allowed_groups (M2M → contacts.ContactGroup) — used when visibility = GROUP
• Image fields: header_image, logo, favicon, animated_logo
• Colour fields: logo_bg_color, header_bg_color, footer_bg_color
• Logo carousel: logo_opacity, logo_text_opacity, logo_slide_interval, logo_text_align, logo_text_valign
• Nav: navigation_layout (LEFT/TOP/RIGHT), navigation_theme (LIGHT/DARK/TRANSPARENT)
• Contact form: contact_show_phone, contact_phone_required, contact_email_required

URL patterns (microsites/urls.py)

ZIP format

mysite-slug.zip
├── site.json          ← UTF-8 JSON, version "1"
├── README.md          ← generated by _build_readme_text(website.title)
├── AI_CONTEXT.md      ← module constant _AI_CONTEXT_TEXT
├── images/
│   ├── header_image.<ext>
│   ├── logo.<ext>
│   ├── favicon.<ext>
│   ├── animated_logo.<ext>
│   └── logos/0.<ext>, 1.<ext> ...
└── files/
    └── <section_slug>_<asset_idx>.<ext>

site.json structure:

• version: "1"
• website: all Website scalar fields (not PKs, not public_slug, not is_published)
• sections: array of sections → assets → blocks. parent_page_index is an array index (not a PK) for cross-DB portability.
• logos: array of WebsiteLogo entries

NOT exported: public_slug, is_published, publish_visibility, allowed_groups, contact messages.

Security validation (_validate_zip_security)

Runs before any DB writes in microsite_import. Raises ValueError on violation:

• Path traversal: any entry name containing .. or starting with / or \
• Unexpected paths: files outside site.json, README.md, AI_CONTEXT.md, images/, files/
• Disallowed image exts: only .jpg .jpeg .png .gif .ico .webp .svg
• Disallowed file exts: only .pdf .md .html .htm .txt
• ZIP bomb: >500 entries, total uncompressed >300 MB, single file >50 MB
• Unsafe HTML in rawhtml/content_text: regex scan for <script, javascript:, on\w+=, <iframe, <object, <embed

Key helper functions (microsites/views.py)

Block type content schemas (PageBlock.content JSONField)

Template architecture

Running tests

python manage.py test microsites

Adding a new block type — checklist

1. Add to _VALID_BLOCK_TYPES set in microsites/views.py
2. Add a case "newtype": branch in msBlockBody() in website_preview.html to return the edit form HTML
3. Add a save/load case in the block save JS handler (msBlockSave() or equivalent) in website_preview.html
4. Add a render branch in _public_canvas.html so it displays on the public site
5. Add the block's schema to _block_row.html for the edit-existing-block path
6. Add the block to the Quick Start tiles array in website_preview.html if it warrants an AI prompt template
7. Add the block type and its content schema to _AI_CONTEXT_TEXT in microsites/views.py so exported ZIPs include it
8. Update this developer guide