Ritual Pug is the source view of a structured ritual. The editor's switch offers Source, Split (both panels side by side) and Visual. 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 of Speech, Action, Note, Section title and Temple hall; an empty line shows the first four as a hint. Use arrow keys and Enter, or tap a choice. Speech and Action then ask for a role; typing a role straight after the slash, such as /ker, offers it directly. Enter on an empty last line of a speech or action leaves it. 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.
Temple hall lists the Golden Dawn hall presets by grade, as does typing a grade straight after the slash, such as /zel, and the toolbar’s Insert… dialog. Each inserts a copy of the preset that the ritual then owns. A hall may stand at the top level or directly inside a note, summary, list item or to-do. The slash command replaces its line there, or follows a speech or action from its last line; elsewhere it is not offered. The toolbar puts the hall after the block holding the cursor, at the nearest place a hall may stand. For source, the temple hall editor copies a hall’s Pug without IDs, ready to paste at the top level; indent it to put the hall in a note.
The temple hall editor works on one hall outside any ritual: start from a preset, edit it on the drawing or in its Pug, side by side if you like, with undo and redo. It keeps the hall as a draft in that browser only, shares it as a link that holds the hall itself, and exports it as SVG or PNG. To keep a hall with a ritual’s history, copy its Pug source into the ritual’s source, or insert a temple hall there and choose Edit hall to edit it in place. In the drawing, an officer or banner dragged along the dais or a banner row changes places (Alt and the arrow keys do the same; an Alt-drag places it freely), and an item, marker or officer dropped on an altar, platform or throne that takes it stands on it. The properties of what is selected stand beside the drawing where there is room, and otherwise at the foot of the screen, where they can be hidden and shown again. A hall with warnings shows how many beside Edit hall.
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. Problems in a temple hall, such as an unknown tag or attribute or a value out of range, are warnings: underlined in yellow and listed in Problems, they do not stop saving, and the hall still draws.
//- 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, ${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, ${candidate}, to the 0=0 grade.
grade(grade="0=0")/
In text, ${candidate} inserts a variable and 0=0 a grade, as in the earlier Pug editor. Generated source adds their IDs, as ${candidate#…} and 0=0#…. A grade needs a space or punctuation other than a full stop on each side, so 3.1=2 stays text. To keep such text literal, write it as #[ritualText(value="${candidate}")/]; the editor does this itself for text that only looks like a shortcut. The grade(grade="0=0")/ and var(name="candidate")/ tags still work.
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.