Graphene.ReverseMarkdown 1.26.8.18

DocumentCreator / ReverseMarkdown

Overview

• DocumentCreator is a small toolset and library for converting HTML to Markdown and for assembling documents.
• This repository includes a forked and extended version of the ReverseMarkdown library used by the project, adapted to emit machine-readable descriptions of interactive HTML elements for LLMs and automation.

Interactive JSON wrapper for LLMs

• When enabled, the HTML→Markdown conversion can emit JSON descriptions of interactive elements using a compact wrapper format so LLMs (or other consumers) can detect UI elements in the Markdown stream.
• Wrapper format: <<INTERACTIVE::tag::JSON>>
  • tag is the original HTML tag name (for example button, input, select, textarea, a, option, details, summary, dialog, menu, menuitem).
  • JSON is a compact JSON object describing the element, its attributes and its interaction-relevant state.

How to enable

• Call the converter with the boolean flag: Convert(html, includeInteractive: true).
• API locations:
  • Converter entry: ReverseMarkdown/Converter.cs
  • New converter: ReverseMarkdown/Converters/InteractiveJsonConverter.cs
  • Context flag: ReverseMarkdown/ConverterContext.cs

JSON payload schema (summary)

• schemaVersion (int): version of the payload schema.
• id (string): deterministic id or generated id for the element (may be based on id attribute or generated guid).
• type (string): HTML tag name.
• attributes (object): map of element attributes (class, id, name, type, placeholder, value, href, role, aria-* etc.).
• text (string): visible text content (if applicable).
• state (object): interaction-relevant properties, e.g.:
  • enabled (bool) whether the element is enabled
  • checked (bool) for checkboxes/radios
  • selected (bool) for options
  • open (bool) for details/dialog
• options (array): for select elements an array of options with { value, text, selected }.
• path (string): approximate XPath or DOM path to help locate element in original document.
• timestamp (string): ISO-8601 when the descriptor was generated.

Notes for LLMs / consumers

• Recognize the wrapper token <<<INTERACTIVE:: and parse until the closing >>>.
• Split on the first two :: separators to extract tag and the JSON payload.
• Parse JSON with a tolerant JSON parser. attributes and state fields give actionable signals.
• Example wrapper: <<INTERACTIVE::button::{"schemaVersion":1,"id":"btn-1","type":"button","attributes":{"class":"primary","text":"Send"},"state":{"enabled":true}}>>
• The converter intentionally emits full value contents for input elements (including password inputs) if those values existed in the source HTML. Treat these values as potentially sensitive when processing or logging.

Design/Implementation notes

• The converter uses an LLM-friendly, compact JSON representation to make it easy for downstream LLMs to extract UI structure and to reason about user interactions (e.g., which buttons exist, which inputs are filled, which options are selected).
• Invisible or hidden elements are skipped (attributes like hidden, aria-hidden, or style="display:none"), unless you change the visibility heuristics in ReverseMarkdown/Converters/InteractiveJsonConverter.cs.

Examples

• C# usage:

var converter = new ReverseMarkdown.Converter();
string md = converter.Convert(htmlString, includeInteractive: true);
// md now contains regular markdown plus wrapper lines like:
// <<<INTERACTIVE::input::{"schemaVersion":1,...}>>>

• Regex to detect wrappers (simple):

/<<<INTERACTIVE::([a-zA-Z0-9_-]+)::(.*?)>>>/s

• LLM hint: treat each wrapper as a separate structured observation. For user-interaction planning, map type+state into possible actions (click, type, select, open, etc.). The repository intentionally omits an actions array — an LLM can infer possible actions from the tag and state.

Security & privacy

• Because input values (including type="password") can be included in the descriptors, do not send converted output containing sensitive values to external services without scrubbing or user consent.

Build & test

• To build the solution:

dotnet build DocumentCreator.sln

• To run quick checks, create a small harness that calls Converter.Convert(html, true) and prints output to verify wrappers are emitted.

Contributing

• If you change the wrapper schema, increment schemaVersion and document the change here so downstream LLM prompts can be updated.

Files of interest

• ReverseMarkdown/Converter.cs — conversion entrypoint and new boolean flag.
• ReverseMarkdown/ConverterContext.cs — contains IncludeInteractive flag.
• ReverseMarkdown/Converters/InteractiveJsonConverter.cs — serializer and visibility heuristics.

License

• See project root for license and original ReverseMarkdown project licensing notes.