trying to port web app starter from PHP

site/doc/pages/markdown_to_html.txt

@@ -0,0 +1,100 @@
+:sig
+String markdown_to_html(String src)
+String markdown_to_html(String src, DTree options)
+
+:params
+src : markdown source text
+options : optional markdown options tree
+return value : rendered HTML string
+
+:desc
+Renders Markdown source into HTML and returns the generated markup as a `String`.
+
+`markdown_to_html()` does not write to the output stream directly. This keeps it aligned with the UCE naming convention where `render_*` names are reserved for direct-output helpers.
+
+Because the return value is HTML markup, embed it with `<?: markdown_to_html(...) ?>`, `print(markdown_to_html(...))`, or pass it through a component.
+
+By default the function aims at a practical GitHub-flavored Markdown target, including tables, task lists, fenced code blocks, autolinks, and strikethrough.
+
+:Example
+`DTree options;`
+`options["components"][":::warning"] = "components/markdown/warning";`
+`options["components"]["node.code_block"] = "components/markdown/code_block";`
+`String html = markdown_to_html(file_get_contents("guide.md"), options);`
+`print(html);`
+
+:SupportedSyntax
+- headings with `#` or setext underlines
+- paragraphs
+- ordered and unordered lists
+- task lists
+- blockquotes
+- fenced code blocks
+- horizontal rules
+- tables
+- inline emphasis, strong, strikethrough, code spans
+- links, images, and bare `http://` / `https://` URLs
+- `:::name ... :::` directive blocks
+
+:Options
+`options["gfm"]`
+Defaults to true.
+Turns on GitHub-style extras such as tables, task lists, autolinks, and strikethrough.
+
+`options["allow_html"]`
+Defaults to false.
+When true, raw HTML blocks and inline tags may pass through as `raw_html` nodes instead of being escaped as plain text.
+
+`options["components"]`
+Declares renderer extension points using normal UCE components.
+
+Exact directive hooks:
+`options["components"][":::warning"] = "components/markdown/warning"`
+This hook is selected for `:::warning ... :::` blocks.
+
+Generic node hooks:
+`options["components"]["node.code_block"] = "components/markdown/code_block"`
+`options["components"]["node.table"] = "components/markdown/table"`
+`options["components"]["node.link"] = "components/markdown/link"`
+`options["components"]["node.directive"] = "components/markdown/directive"`
+
+If both an exact directive hook and a generic `node.directive` hook exist, the exact directive hook wins.
+
+:ComponentProps
+When a markdown hook component is called, its props arrive in `context.call`.
+
+Useful fields include:
+`context.call["hook"]` : matched hook key such as `:::warning` or `node.code_block`
+`context.call["target"]` : resolved component target name
+`context.call["default_html"]` : renderer output without the hook
+`context.call["children_html"]` : already-rendered child HTML
+`context.call["node"]` : full AST node
+`context.call["type"]` : node type
+`context.call["name"]` : directive name when applicable
+`context.call["argument"]` : directive remainder after the name
+`context.call["text"]` : source text for nodes such as `code_block`
+`context.call["lang"]` : fenced code language
+`context.call["href"]` / `context.call["src"]` / `context.call["title"]`
+`context.call["options"]` : full markdown options tree
+
+This lets a component either replace the HTML completely or wrap `default_html` / `children_html`.
+
+:DirectiveSchema
+Directive blocks use this form:
+`:::warning title="Heads up"`
+`Body markdown here`
+`:::`
+
+The parser stores:
+`node["name"] = "warning"`
+`node["argument"] = ...` for bare trailing text
+`node["attrs"] = ...` for parsed `key=value` pairs such as `title="Heads up"`
+
+This makes directive components a good fit for alerts, callouts, cards, embeds, and any richer page-level markdown extension.
+
+:see
+markdown_to_ast
+component
+render_component
+json_decode
+String