DOCSEARCHbyAlgolia
Submit Docs

towxml

repository·master·Indexed 25 days ago

https://github.com/sbfkcel/towxml

A rendering engine that converts HTML and Markdown into WXML (WeiXin Markup Language), enabling WeChat Mini Programs to display rich text content. Version 3.3.1 supports Echarts, LaTeX mathematical formulas, yuml flowcharts, code syntax highlighting, and multiple themes. It provides a parsing system to map standard HTML tags to WXML components and supports both pre-parsing and post-parsing data.

Tokens
1.1K
Snippets
0
Records
8
Agent score
84%

What's inside towxml

  1. Overview of Towxml

    master
    Towxml is a rendering library designed to convert HTML and Markdown into WXML (WeiXin Markup Language). It is primarily used to solve the issue of rendering Markdown and HTML content directly within WeChat Mini Programs.

  2. Features of Towxml 3.0

    master

    Towxml 3.0 is the recommended version, offering a smaller footprint and faster speeds compared to 2.x. Key features include:

    • Advanced Rendering: Support for Echarts charts, LaTeX mathematical formulas, and yuml flowcharts.
    • Customization: Support for on-demand builds (to reduce bundle size), multiple theme switching, and event binding for custom extensions.
    • Rich Content: Code syntax highlighting with line numbers, emoji support, Markdown TodoLists, and support for most HTML elements (tables, video, images, etc.).
    • Optimization: Optimized Chinese typography and support for both pre-parsing and post-parsing data.

  3. Setup and Usage for Towxml 3.0

    master

    Important Note

    Do not pull the code directly for use in version 3.0. You must build the library according to your specific needs to obtain the final code.

    Getting Started

    To use Towxml 3.0, follow these steps in order:

    1. Build Towxml: Follow the build guide to generate the necessary files.
    2. Run the Demo: It is highly recommended to run the provided demo project successfully before attempting integration into your own project.
    3. Implementation: Follow the specific usage guides for your environment (e.g., standard WeChat Mini Program or uniapp).

    Advanced Features

    • Echarts: Specific configuration is required for chart support.
    • Math & Diagrams: Follow guides for LaTeX and yuml flowcharts.
    • uniapp: There is a specific integration pattern for using Towxml 3.0 within uniapp.

  4. Troubleshooting LaTeX Formula Rendering

    master

    If mathematical formulas are not rendering correctly:

    • Escaping Special Characters: If you are storing the content within a variable, ensure that special symbols within the formula are properly escaped/transpiled.
    • Loading Method: Refer to the demo that loads content via http for the correct implementation pattern.

  5. Configure the parse function options

    master

    When calling the parse function, you can provide an option object to control the output structure and behavior:

    KeyTypeDescription
    themestringSets the visual theme. Options: 'light' (default) or 'dark'.
    basestringA base URL used to resolve relative src paths in tags like <img> or <audio>.
    eventsobjectAn object containing event handlers. These are stored in a global _events object for components to access during runtime.

    Note: The theme value is stored in a global _theme variable during parsing.

  6. Convert HTML or Markdown to WXML using the default export

    master

    The main entrypoint of towxml is a function that converts either Markdown or HTML strings into WXML (WeChat XML) format.

    Parameters:

    • str (string): The source content to be parsed.
    • type (string): The format of the source content. Supported values are 'markdown' and 'html'.
    • option (object, optional): Configuration options for the parsing process. Defaults to an empty object {}.

    Returns:

    • A parsed result object compatible with WeChat Mini Programs.

    Errors:

    • Throws an error if type is not 'markdown' or 'html'.

  7. Parse Markdown strings with the default exporter

    master
    The module exports a single function that takes a Markdown string as input and returns the rendered HTML string. It uses internal configuration to handle features like syntax highlighting, line numbers, and emoji rendering.

  8. Parse HTML strings to WXML-compatible objects

    master

    The default export of parse/index.js is a function that takes an HTML string and an options object. It processes the HTML (extracting content from <body> tags if present) and converts it into a structured object suitable for WXML rendering.

    Key features:

    • Tag Conversion: Automatically maps standard HTML tags to WXML components (e.g., <a> becomes navigator, audio becomes audio-player).
    • Base URL Support: If a base path is provided in the options, relative src attributes in images or media are automatically resolved.
    • Theme Support: Supports a theme option ('light' or 'dark').
    • Event Handling: Allows passing an events object to map custom event handlers that components can trigger.
    • Class Injection: Automatically adds CSS classes to elements following the pattern h2w__[tagname] [original-class].