Front Matter (Page Options)

Front matter must be at the very top of the page and wrapped with +++ delimiters.

+++
PAGE_TITLE = "My Page"
CONTAINER_MAX_WIDTH = "900px"
CONTENT_FONT = "Inter DM_Serif_Display"
CONTENT_TEXT_COLOR = "#1f2937 #e5e7eb"
SAFETY_PAGE_WARNING = "sensitive"
OPTION_DISABLE_SEARCH_ENGINE = true
+++

Supported Front Matter Options

Option	Type	Notes
`PAGE_TITLE`	string	Browser/page title
`CONTAINER_MAX_WIDTH`	string	e.g. `800px`, `65ch`
`CONTENT_FONT`	string	Space-separated Google fonts, use underscores for spaces
`CONTAINER_INNER_BACKGROUND_COLOR`	string	One value, or light/dark pair
`CONTAINER_OUTER_BACKGROUND_IMAGE`	string	Image URL
`CONTAINER_BORDER_RADIUS`	string	e.g. `16px`
`CONTENT_TEXT_SIZE`	string	Space-separated sizes
`CONTENT_TEXT_COLOR`	string	One value, or light/dark pair
`SAFETY_PAGE_WARNING`	enum	`adult`, `sensitive`, `epilepsy`, `custom`
`OPTION_DISABLE_SEARCH_ENGINE`	boolean	`true` or `false`

Custom styling of the page itself (especially text/background color overrides) is not recommended due to contrast and readability issues across themes and devices.

Dynamic Inserts (v1)

Dynamic Inserts use Pipe Declaration Blocks.

Every dynamic insert:

|> <type>
   property=value
   property=value

Indentation is required (2+ spaces). Properties are one per line. Strings with spaces must use quotes " ".

All execution happens on load in the browser. There are no proxies, server transforms, or background jobs.

Supported Insert Types

form
button
fetch
refresh
random
popup

Global Rules

1) Variable Interpolation

All dynamic values use:

{{scope.name}}

Scopes:

rand.<label>
form.<group>.<input>
fetch.<alias>.<field>

Example:

{{rand.session}}
{{form.account.email}}
{{fetch.products.title}}

2) Execution Order

Dynamic inserts execute top-to-bottom.

Order:

random
fetch (auto-run only)
others triggered by interaction

3) XML is Mandatory

All APIs:

Must return XML
Must follow fixed structure:

<response>
  <meta>
    <status>success</status>
  </meta>
  <data>
    ...
  </data>
</response>

Frontend reads only <data>.

1) Random

Generates reusable value.

Syntax

|> random
   label=session
   type=number
   length=4
   persist=true
   cookie=SID
   cookieDays=30

Required Properties

label   (unique identifier)
type    number | string | uuid
length  (required if number or string)
persist (optional, true|false, default=false)
cookie  (optional cookie name, default=pretrey_rand_<label>)
cookieDays (optional cookie TTL in days, default=30)

Output Access

{{rand.session}}

Random values are immutable once generated. If persist=true, the value is reused from cookie on reload (use cookie=SID for a stable SID key).

2) Form

A form defines a form group.

Syntax

|> form
   group=account
   action="/api/register.xml?token={{rand.session}}"
   method=POST

   input=username  label="Username" type=text required=true
   input=email     label="Email"    type=email
   input=password  label="Password" type=password

   submit="Create Account"

Required Properties

group
action
method (POST | GET)

Input Definition Format

input=<name>
   label="Text"
   type=text|email|password|number|hidden
   required=true|false
   value="default"

Shorthand allowed (single line):

input=username label="Username" type=text

Submit Options (Optional)

feedback=true|false
successMessage="Custom success text"
errorMessage="Custom error text"
reloadOnSubmit=true|false

feedback=true shows submit success/error text under the submit button.
reloadOnSubmit=true reloads the page after a successful submit.

Submission Behavior

On submit:

Collect all input values in that group.
Send as XML:

<form>
  <username>value</username>
  <email>value</email>
</form>

Submit to action URL.
Replace {{rand.*}} before sending.

Accessing Form Values Elsewhere

{{form.account.username}}

3) Button

Buttons are independent action triggers.

Syntax

|> button
   label="Save"
   icon=fa-save
   action=submit
   target=account

Required Property

label
action

Action Types

Action	Required Target
submit	group name
fetch	fetch alias
refresh	none
open	url
popup	popup id

Examples

Submit form:

|> button
   label="Submit"
   action=submit
   target=account

Fetch trigger:

|> button
   label="Load Products"
   action=fetch
   target=products

Open link:

|> button
   label="Visit Site"
   action=open
   target="https://example.com"

Refresh:

|> button
   label="Reload"
   action=refresh

Open popup:

|> button
   label="Show Help"
   action=popup
   target=helpModal

4) Fetch

Fetch loads XML and renders data.

Syntax

|> fetch
   alias=products
   src="/api/products.xml?sid={{rand.session}}"
   display=carded
   cardSize=auto
   trigger=manual

Required Properties

alias
src
display

Optional

trigger=auto | manual
cardSize=auto | small | half | full  (only for display=carded)

Default = auto When cardSize=auto, use a marker as the first non-empty line of each card template:

#   = full-width card
##  = half-width card
(no marker) = small card

Display Types

list
carded
horizontal

XML Structure for Fetch

Expected XML:

<response>
  <data>
    <items>
      <item>
        <title>Product 1</title>
        <description>Desc</description>
        <price>$10</price>
      </item>
    </items>
  </data>
</response>

Rendering Rules

Each <item> becomes one rendered entity.

Inside rendering block:

|> fetch
   alias=products
   src="/api/products.xml"
   display=carded

   template:
     ##
     **{{title}}**
     **{{price}}**
     {{description}}

Field Access Rules

Fields come directly from <item> children.
Markdown formatting allowed inside template.
Unknown fields render empty.

Display Behavior

list

Vertical stacked items

carded

Grid cards

3 Card Layout Presets (`display=carded`)

small = small box
half = box spanning half of the page width
full = box spanning the entire page width Use cardSize= to force one layout for all cards in a fetch block:

cardSize=small | half | full | auto

With cardSize=auto, size is decided per-card by marker on the first non-empty template line:

#   => full (entire width)
##  => half (half width)
no marker => small box

horizontal

Horizontal scroll cards

5) Popup

Popup shows a modal based on triggers.

Syntax

|> popup
   id=helpModal
   title="Need Help?"
   description="This popup can be opened by trigger."
   trigger="refresh,form:contact:success,fetch:products:error"
   dismiss="Close"

Trigger Values

refresh
form:<group>:success
form:<group>:error
fetch:<alias>:success
fetch:<alias>:error

Multiple triggers are comma-separated.
Popup can also be opened by button action: action=popup target=<popup-id>.

6) Refresh

Refresh reloads:

All fetch blocks
All random blocks
Resets form values

Syntax

|> refresh

Or button trigger:

|> button
   label="Refresh Page"
   action=refresh

Random + Fetch Integration

Example:

|> random
   label=session
   type=number
   length=4

|> fetch
   alias=items
   src="/api/items.xml?sid={{rand.session}}"
   display=list

If random=session=1233

Actual request:

/api/items.xml?sid=1233

Complete Valid Example

# Dashboard

|> random
   label=session
   type=number
   length=4

|> fetch
   alias=products
   src="/api/products.xml?sid={{rand.session}}"
   display=carded
   trigger=manual

   template:
     ## {{title}}
     **{{price}}**
     {{description}}

|> button
   label="Load Products"
   icon=fa-box
   action=fetch
   target=products

|> form
   group=contact
   action="/api/contact.xml?sid={{rand.session}}"
   method=POST

   input=name  label="Name" type=text required=true
   input=email label="Email" type=email

   submit="Send Message"

|> button
   label="Refresh"
   action=refresh
|> popup
   id=submitOk
   title="Form submitted"
   trigger="form:contact:success"
|> popup
   id=fetchError
   title="Fetch failed"
   trigger="fetch:products:error"

Final Consistency Guarantees

Every insert starts with |> type
All properties are key=value
All dynamic values use {{scope.name}}
XML format is fixed
Rendering requires template: block
Buttons target aliases or groups only
Random values immutable per page load

Documentation

Front Matter (Page Options)

Supported Front Matter Options

Dynamic Inserts (v1)

Supported Insert Types

Global Rules

1) Variable Interpolation

2) Execution Order

3) XML is Mandatory

1) Random

Syntax

Required Properties

Output Access

2) Form

Syntax

Required Properties

Input Definition Format

Submit Options (Optional)

Submission Behavior

Accessing Form Values Elsewhere

3) Button

Syntax

Required Property

Action Types

Examples

4) Fetch

Syntax

Required Properties

Optional

Display Types

XML Structure for Fetch

Rendering Rules

Field Access Rules

Display Behavior

list

carded

3 Card Layout Presets (display=carded)

horizontal

5) Popup

Popup shows a modal based on triggers.

Syntax

Trigger Values

6) Refresh

Syntax

Random + Fetch Integration

Complete Valid Example

Final Consistency Guarantees

3 Card Layout Presets (`display=carded`)