Escribal
Back to Docs

Markdown

Advanced

This group provides advanced operations on a Markdown document: fill a template with values, join another document onto this one, split the document into sections by heading or pull out one section, add CSS/HTML attributes to a block, insert raw HTML, prefix headings, remove whole kinds of block, and inspect or render the document (its structure, a single block, or a sanitized HTML version). Some of these instructions rewrite the document; others only read it and save a result.

Prerequisite: the workflow must already have a Markdown document created (with Create Markdown) or opened. Every instruction here works on that open document.

These concepts recur across the instructions in this group; they are explained here once.

  • Document: indicates which document in the workflow the instruction applies to. If left empty, the current document is used. If the document doesn’t exist (or is not a Markdown/text document), the instruction simply does nothing.

  • Some instructions change the document, others only read it. These change the document: Add Attributes To Block, Apply Template, Combine Documents, Insert Raw HTML, Prepend To Headings and Remove Blocks By Type. These are read-only and just save a result: Convert To AST, Get Section, Render Block To HTML, Sanitize HTML and Split By Headings.

  • Dynamic values @name: the text fields (such as Template, Values, Additional markdown, Separator, CSS class, HTML id, HTML, Prefix and Block type) accept a saved value: type @ followed by its name and the engine substitutes the value at run time. This does not apply to numeric fields.

  • Saving a result (Save … fields): several instructions save their output into a named value (Save markdown, Save AST, Save section, Save HTML, Save sanitized, Save result, Save section count, Save removed count). If you leave that field empty, nothing is saved.

  • Headings and levels: instructions that work by heading level accept a level from 1 (top level, a single #) to 6 (deepest); values outside that range are brought back into it.

  • Blocks: several instructions (Add Attributes To Block, Render Block To HTML) work on blocks — the pieces of the document separated by blank lines, numbered starting at 1. If the block number is outside the document, the instruction does nothing (or saves an empty result).

  • Sections: Split By Headings and Get Section cut the document at every heading of a chosen level; each piece (a heading and everything under it up to the next one) is a section, numbered starting at 1.

  • “From variable” fields: the numeric fields Block number, Heading level and Section number each have a companion “from variable” field:

    • If you leave it empty, the number typed in the normal field is used.
    • If you fill it in with the name of a saved value, the engine ignores the normal field and reads the number from that variable.

    This is mainly for chaining instructions (for example, an earlier instruction saves a section number that Get Section then reads). If you only work with fixed values, you can ignore it.

Add Attributes To Block .md

Attaches a CSS class and/or an HTML id to a block, so that when the document is rendered to HTML that block carries them.

When to use it: to style or target a specific paragraph, list or heading in the HTML output (for example, to give it a class your stylesheet knows about).

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Block number The number of the block to tag (blocks start at 1) 1 No
CSS class The class name to attach (accepts @name) (empty) No
HTML id The id to attach (accepts @name) (empty) No
Block number (from variable) Reads the block number from a saved value (empty) No

Important behavior: blocks are the pieces separated by blank lines. If the block number is outside the document, nothing happens. If both CSS class and HTML id are empty, nothing happens. The attributes are written after the block using the {#id .class} syntax that the HTML renderer understands.


Apply Template .md

Replaces the whole document with a template in which {{key}} markers have been filled in from a list of values.

When to use it: to produce a document from a fixed layout, dropping in names, dates or other values collected earlier in the workflow.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Template The template text, with {{key}} markers to be filled in (accepts @name) (empty) Yes
Values The values to insert, as key=value pairs separated by | — e.g. name=John|date=2024-01-01 (accepts @name) (empty) No
Save markdown Name under which the resulting document text is saved. Empty = don’t save (empty) No

Important behavior: if Template is empty, nothing happens. The template becomes the new content of the document (the previous content is discarded). Each {{key}} whose key appears in Values is replaced by its value; markers with no matching value are left as they are.


Combine Documents .md

Appends more Markdown to the end of the current document, with a separator in between.

When to use it: to stitch a second piece of content (a saved section, another document’s text) onto the one you are building.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Additional markdown The Markdown text to append (accepts @name) (empty) Yes
Separator Text placed between the two parts (accepts @name) \n\n---\n\n (a horizontal rule) No
Save markdown Name under which the combined document text is saved. Empty = don’t save (empty) No

Important behavior: if Additional markdown is empty, nothing happens. By default the two parts are separated by a horizontal rule (---); set Separator to change that, or clear it to join the two parts with nothing in between.


Convert To AST .md

Reads the document’s structure and saves a human-readable summary of it — one line per top-level block, with its type and a short text preview. This instruction only reads; it does not change the document.

When to use it: to inspect how the engine sees the document (which blocks it contains) — useful for debugging a workflow.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Save AST Name under which the structure summary is saved. Empty = don’t save (empty) No

Important behavior: the document is not changed. The summary lists each block’s type — the same vocabulary as Remove Blocks By Type (heading, paragraph, list, code, quote, table, html, rule) — with up to the first 40 characters of its text.


Get Section .md

Splits the document into sections by heading level and saves the text of one section. This instruction only reads; it does not change the document.

When to use it: to pull out a single part of the document (to reuse it elsewhere, or to combine it into another document).

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Heading level The heading level the document is split at, from 1 (top) to 6 (deepest) 1 No
Section number The number of the section to return (sections start at 1) 1 No
Heading level (from variable) Reads the heading level from a saved value (empty) No
Section number (from variable) Reads the section number from a saved value (empty) No
Save section Name under which the section’s text is saved. Empty = don’t save (empty) No

Important behavior: the document is split at every heading of the chosen level; each section runs from one such heading up to the next. If the section number is outside the document, an empty result is saved.


Insert Raw HTML .md

Adds a piece of raw HTML to the document, on its own lines.

When to use it: to include HTML that has no Markdown equivalent (a custom block, an embedded widget) so it survives into the HTML output.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
HTML The raw HTML to insert (accepts @name) (empty) Yes

Important behavior: if HTML is empty, nothing happens. The HTML is added at the end of the document, surrounded by blank lines so it is kept as a separate block.


Prepend To Headings .md

Adds a prefix in front of the text of every heading at a given level.

When to use it: to number or badge a set of same-level headings at once (for example, to put an emoji or a label before each section title).

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Heading level The level of the headings to change, from 1 (top) to 6 (deepest) 1 No
Prefix The text to place before each heading’s text (accepts @name) (empty) Yes
Heading level (from variable) Reads the heading level from a saved value (empty) No

Important behavior: if Prefix is empty, nothing happens. Only headings at exactly the chosen level are affected; the heading marks (#) are kept and the prefix is inserted before the text.


Remove Blocks By Type .md

Removes every block of a given kind from the document and saves how many were removed.

When to use it: to strip out all code blocks, all quotes, all tables, etc. in one step.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Block type The kind of block to remove: Code block (code), Quote (quote), Heading (heading), Paragraph (paragraph), List (list), Table (table), Raw HTML (html) or Horizontal rule (rule) code (Code block) No
Save removed count Name under which the number of removed blocks is saved. Empty = don’t save (empty) No

Important behavior: Code block covers both fenced and indented code, and List covers the list and its items. If no block of that kind is present, the document is left unchanged and the saved count is 0. Because Block type is a fixed list of choices, it does not accept @name.


Render Block To HTML .md

Renders a single block to HTML and saves it. This instruction only reads; it does not change the document.

When to use it: to obtain the HTML of one specific part of the document without rendering the whole thing.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Block number The number of the block to render (blocks start at 1) 1 No
Block number (from variable) Reads the block number from a saved value (empty) No
Save HTML Name under which the block’s HTML is saved. Empty = don’t save (empty) No

Important behavior: blocks are the pieces separated by blank lines. If the block number is outside the document, an empty result is saved.


Sanitize HTML .md

Produces a safe HTML version by stripping out dangerous tags and attributes. This instruction only reads; it does not change the document.

When to use it: to obtain HTML that is safe to publish, with scripts and other risky content removed.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
HTML HTML to sanitize; leave empty to sanitize the document’s own rendered HTML (accepts @name) (empty) No
Save sanitized Name under which the sanitized HTML is saved. Empty = don’t save (empty) No

Important behavior: if HTML is empty, the current document is first rendered to HTML and that is sanitized. The cleanup removes script, iframe, object, embed, form and style tags, event handler attributes (onclick, etc.), and javascript: and data: links. The document itself is not changed.

Limitation — do not treat the result as guaranteed-safe HTML. The cleanup works by text patterns, so deliberately crafted HTML (malformed or nested tags, unusual encodings, exotic attributes) can get through. It is useful for tidying up HTML you already trust — your own content, or content from a source you control. If the HTML comes from an untrusted source and will be published on a web page, sanitize it with a dedicated tool before publishing; this instruction is not a security barrier.


Split By Headings .md

Splits the document into sections by heading level and saves a numbered summary of the section headings (and, optionally, how many sections there are). This instruction only reads; it does not change the document.

When to use it: to get an overview of the document’s sections, or to find out how many there are before acting on them.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Heading level The heading level the document is split at, from 1 (top) to 6 (deepest) 1 No
Heading level (from variable) Reads the heading level from a saved value (empty) No
Save result Name under which the numbered summary of sections is saved. Empty = don’t save (empty) No
Save section count Name under which the number of sections is saved. Empty = don’t save (empty) No

Important behavior: the document is split at every heading of the chosen level. The saved summary lists each section by number with the text of its first line; the section count is the number of non-empty sections found.


This documentation is the help of the application, and it comes underCreative Commons Attribution 4.0.