Docs / Files, mail, documents

a9script authoring pack — markdown functions

The markdown functions, with their arguments and a line of real script each. Called by bare name; nothing is imported. A call marked pauses does real work outside the script: the run is saved, and continues on the next line with the result.

This is one part of the authoring pack — how a script is executed at all is the model part, and the other groups of functions are parts of their own. All of them are named at the end.

Generated — do not edit. Every block of script below is executed by the platform’s own test suite, and every error message is the one the platform produces today, so none of this can be what was true when someone last wrote it down.

markdownToHtml(markdown, options?) — pauses

Turns markdown into HTML — headings, lists, tables, links, code blocks, bold and italic, the dialect people write in. It does not make the result safe. Markdown is allowed to contain HTML, so anything dangerous in the markdown is still dangerous in the answer: if any part of it came from outside your own script — a form field, an email, a webhook — pass the answer through sanitizeHtml before it reaches a reader.

• markdown (string) — The markdown to read.
• options (object, optional) — { lineBreaks }. lineBreaks defaults to false, which is how markdown normally reads: a single newline is a space, and a blank line starts a paragraph. Set it to true when the text was typed in a box where people press Enter and expect a new line. Any other option is refused by name.

Answers: The HTML, as text. Characters that would otherwise be read as markup are escaped in ordinary text, but HTML written directly in the markdown is passed through as written — which is exactly why untrusted input needs sanitizeHtml.

const html = markdownToHtml("# Report\n\nSales were **up**.");
log(sanitizeHtml(html));

sanitizeHtml(html, options?) — pauses

Removes everything from HTML that could run, load or frame anything, and answers what is left. Works from a list of what is ALLOWED rather than a list of what is forbidden — so a tag nobody has heard of is removed too, which is what makes it safe against things nobody thought of yet.

• html (string) — The HTML to clean.
• options (object, optional) — { allowedTags, allowedAttributes }. Both replace the standard list rather than adding to it, so a reader of the call can see everything it permits: allowedTags is a list of tag names, allowedAttributes an object of tag name to the attributes that tag may keep. Passing an empty list for both answers plain text. Whatever you allow, a link or image address may still only use http, https, mailto or tel — widening cannot re-admit a dangerous one.

Answers: The cleaned HTML. A removed tag keeps the words it wrapped, so no content disappears — except for a script or a style block, whose contents go with it. Cleaning something already cleaned changes nothing.

const safe = sanitizeHtml("<p>Hi</p><script>alert(1)</script>");
log("cleaned to: " + safe);

escapeHtml(text) — pauses

Turns the five characters that change how markup is read — &, <, >, " and ' — into the codes that stand for them. Use it when you are building HTML yourself and want a value to appear as TEXT, exactly as written, rather than becoming part of the markup around it.

• text (string) — The text to escape.

Answers: The same text with those five characters replaced. Everything else — every alphabet, every accent, every emoji — is left exactly as it was.

const name = escapeHtml("Ben & Jerry's <team>");
log("<p>Hello, " + name + "</p>");

stripMarkdown(markdown) — pauses

Answers the plain words of a markdown document, with all of its formatting removed — for a plain-text version of a message, a summary line, or anywhere a reader will not see markup.

• markdown (string) — The markdown to strip.

Answers: The text, with headings, emphasis, links and tags gone and the words kept. A link becomes the words it linked, not the address.

const plain = stripMarkdown("# Title\n\nSome **bold** words.");
log(plain);

markdownToPdf(markdown, options?) — pauses

Draws a markdown document as a PDF, and answers it the way createPdf does. Headings become headings, lists become lists, tables become tables and a rule becomes a rule; bold and italic are flattened to their words, because a drawn document holds text rather than styled runs. Markdown has six heading levels and a document draws three, so a level 4, 5 or 6 heading is drawn at the smallest size rather than lost.

• markdown (string) — The markdown to draw.
• options (object, optional) — { title } — the name the document carries, exactly as createPdf takes it: a reader meets it in their PDF viewer’s title bar, never on the page. Any other option is refused by name.

Answers: The document as base64 text — the same shape writeBlob takes. The same rules apply as when you build a document by hand, including which characters a document can draw: markdown that nests far deeper than anyone writes is refused rather than read.

const pdf = markdownToPdf("# Invoice 4711\n\n| item | amount |\n| --- | --- |\n| Widget | 12.50 |", { title: "Invoice 4711" });
log("the document is " + pdf.length + " characters of base64");

The rest of this pack

The page above is everything that is true only HERE. Ask for these parts by name for the rest:

• model — how a script is executed, the shape of its input, the rules enforced while it runs, and the mistakes that do not work here.
• functions-core — the core functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-encoding — the encoding functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-crypto — the crypto functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-text — the text functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-number — the numbers functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-structured — the structured data functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-document — the documents functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-datetime — the date & time functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-email — the email functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-blob — the files functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-mapping — the mapping functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-dataset — the datasets functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-state — the state functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-pagination — the pagination functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-control — the run control functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-functions — the config functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• mistakes — the habits from general JS that do not work here — each with the exact error it produces and the shape to write instead.
• standard-library — every built-in the language itself provides — JSON, Math, Object, String, Array, Number, Map, Set, Date, RegExp and the bare globals — one line each, with an example and its answer.