Ritual Pug is the source view of a structured ritual. You can edit visually, in source, or with both panels side by side. Visual edits regenerate source; valid source edits update the visual panel after a short typing pause. Incomplete syntax keeps the last valid document visible.
The initial layout is split, with source on the left and visual editing on the right; small screens stack the panels. Your last chosen layout is remembered in this browser for both new and existing rituals. Source-only recovery does not replace that preference.
Choose Visual / Ritual Pug when creating a ritual. Older Ritual Text drafts are recovered and converted automatically when valid. Incomplete or conflicting buffers remain available to repair, apply or download; pending saves must resolve before conversion. Block IDs and annotations are preserved. Source Undo covers typing in the current view; visual regeneration, discarding source, and recovery conversion start a fresh source history.
Hover over a speech or action card, or tab to its role heading, to reveal the settings cog. On touch screens the cog stays visible. The same form opens from Edit properties when a task is selected. Choose Say / Speech or Do / Action, then assign selected roles, everyone, or all officers. For a group, the role picker lists optional exceptions. Search by full name or shortcut, or enter a custom role key using letters and numbers, beginning with a letter. Roles declared in the ritual are included too.
All officers retains the existing ritual convention: it excludes Candidate and Member, and includes Aspirant and custom roles. Apply updates the source and keeps the task’s body and ID; the role and speech/action change undo together. Cancel leaves the task unchanged.
Delete task at the bottom of the cog removes the whole card immediately, independently of unfinished settings. Use the brief Undo notification or Ctrl/Cmd+Z to restore its contents and IDs. The notification stops offering Undo after a later edit; normal editor history remains available.
Empty speech and action cards have a full clickable body line, marked Type speech… or Type an action…. Click that line to place the cursor and start typing. These hints are editor-only and are never included in saved source or reader output.
In a fresh, unformatted paragraph, type /say hiero or /do keryx . The final space creates a speech or action card and puts the cursor in its body so you can keep typing. Standard role keys and shortcuts match without case sensitivity; declared and already-used custom role keys keep their exact case. Unknown keys stay as text. Everyone and all officers use all and all-officers; edit more detailed assignments with the cog.
Typing / opens a menu. Use arrow keys and Enter, or tap a choice, to select Say/Do and a role. Search by role name or shortcut. Escape dismisses the menu and keeps that paragraph literal. Undo or immediate Backspace restores the command after conversion. Pasted commands stay literal.
A command in the final paragraph of a task creates a sibling card. Commands midway through a task, inside a list, or inside a note within a task stay literal. Collected footnotes outside tasks support the same commands and canonical undo history. Commands create ordinary tasks in source; they do not introduce a new saved format.
Source errors have red underlines and a marker beside their line number. Hover over either for details, or choose Go to error.F8 jumps to an error; Shift+F8 goes backwards. Problems opens the error list, also available with Ctrl+Shift+M (Cmd+Shift+M on Mac). A folded ID is revealed when you jump to its error. Where only the line is known, the editor underlines that line’s content. Errors clear when corrected.
//- magickli-ritual-pug 1
title(text="Opening") Opening
summary(summary="Preparation")
note Replace this note with preparations for your ritual.
Hiero: Welcome.
* Keryx Open the door.
summary(summary="Closing")
Hiero: The ritual is concluded.
//- magickli-ritual-pug 1.//- comments are allowed.#[…] for inline tags./ means a node has no child collection. A bare tag can have an empty collection or indented children.Author comments and blank separator lines are stored with the tree and survive visual edits, saving and syntax switches. They appear as small annotation items in the visual editor, and are omitted from the reader. Edit their wording in source. Blank lines within Pug literal text or between consecutive pipe-text lines keep Pug’s content whitespace behavior. Use br/ for an explicit reader line break. Indentation and other formatting are regenerated consistently. Multiline comments may use a generated ritualComment(value="…")/ wrapper for exact preservation. Includes, JavaScript, mixins, loops, raw HTML and arbitrary tags are unsupported.
Hiero: Welcome. creates speech; * Keryx Open the door. creates an action. These shortcuts are the default generated spelling for tasks with inline content. Explicit say(role="hiero") and do(role="keryx") also work, and are used for more complex tasks. Roles can be comma-separated, All,All-officers or All-except-hiero.
//- magickli-ritual-pug 1
Hiero: Welcome, #[var(name="candidate")/]. Speak #[b clearly].
* Keryx Open the door.
Generated shortcuts capitalize the first letter of each role. Lowercase initials work too: Hiero: and hiero: refer to the same role. Explicit say(role="…") and do(role="…") preserve the exact role spelling. Names of supported Pug tags, such as note, keep Pug’s colon expansion syntax; use explicit say(role="note") for a role with that name.
Use b, i and a(href="https://example.com")for bold, italic and links. br/ inserts a line break. Footnotes use footnote with child content and footnotes/for their collected reader output.
//- magickli-ritual-pug 1
//- Notes for authors; omitted from the reader.
title(text="Preparation") Preparation
summary(summary="Before starting")
note Prepare the space.
ul
li First item
li Second item
todo Check this wording.
hr/
The separate Title field names the ritual in the list. A titletag creates a heading within the content. Lists use ul orol, containing li items.
//- magickli-ritual-pug 1
declareVar(name="candidate", label="Candidate name", varType="text", default="Guest")/
declareVar(name="direction", label="Direction", varType="select", default="east")
option(value="east", label="East")/
option(value="west", label="West")/
Hiero: Welcome, #[var(name="candidate")/].
grade(grade="0=0")/
Use the visual editor’s Image control after saving a new ritual. It supplies an authorized image URL. Replace the example URL below; altdescribes the image for readers who cannot see it.
//- magickli-ritual-pug 1
img(src="/image.svg", alt="Describe the image", width=320)/
Canonical source includes #id, for example Hiero#Ab3k9Qp7Zx2Mn5Rs: Welcome. IDs are folded into small #… markers by default. Click one to reveal it, or choose Show IDs. Copying source and downloading drafts include the complete IDs. Existing UUID IDs are valid too.
Keep IDs when editing or moving existing blocks. New tags can omit IDs; the editor assigns them. When copying source to create different blocks, remove the copied IDs. Visual copy/paste handles this automatically.
ritualText preserves exact text and boundaries when ordinary Pug text would change whitespace. ritualLegacy preserves opaque content. Keep these generated payloads intact.
//- magickli-ritual-pug 1
ritualText(value="Text with exact trailing space ")/
ritualLegacy(raw={"type":"synthetic-widget","mode":"preserve"})/
Some valid structures require source editing. Their content remains intact. Original Pug revisions stay in history; the new projection is generated from the retained reader/semantic tree rather than replacing it with backup text.