Markdown code fences rendered incorrectly in published ESP-IDF component (PACMAN-714)

[tronical]

The Component Manager version

v1.3.2

ESP-IDF Version

v5.1

python Version

3.11.4

Operating System

macOS 13.5.2

Browser (for https://components.espressif.com Issues)

Safari 16.6, Chrome 116.0.5845.179, Firefox 117.0

Description

We recently uploaded a new component to the ESP-IDF component registry, slint/slint. The README of the component uses markdown and code fences to explain how to use the component in a step-by-step tutorial. The exactly README that we uploaded can be found here:

https://github.com/slint-ui/slint/blob/v1.2.0/api/cpp/esp-idf/slint/README.md

The result can be see at

https://components.espressif.com/components/slint/slint/versions/1.2.0~1

In the markdown of the README we include the following C++ code fence:

#include <stdio.h>
#include <esp_err.h>
#include <bsp/display.h>
#include <bsp/esp-bsp.h>
#include <slint-esp.h>

#if defined(BSP_LCD_DRAW_BUFF_SIZE)
#    define DRAW_BUF_SIZE BSP_LCD_DRAW_BUFF_SIZE
#else
#    define DRAW_BUF_SIZE (BSP_LCD_H_RES * CONFIG_BSP_LCD_DRAW_BUF_HEIGHT)
#endif

#include "appwindow.h"

extern "C" void app_main(void)
{
    /* Initialize display  */
    esp_lcd_panel_io_handle_t io_handle = NULL;
    esp_lcd_panel_handle_t panel_handle = NULL;
    const bsp_display_config_t bsp_disp_cfg = {
        .max_transfer_sz = DRAW_BUF_SIZE * sizeof(uint16_t),
    };
    bsp_display_new(&bsp_disp_cfg, &panel_handle, &io_handle);

     /* Set display brightness to 100% */
    bsp_display_backlight_on();

    std::optional<esp_lcd_touch_handle_t> touch_handle;

    /* Allocate a drawing buffer */
    static std::vector<slint::platform::Rgb565Pixel> buffer(BSP_LCD_H_RES * BSP_LCD_V_RES);

    /* Initialize Slint's ESP platform support*/
    slint_esp_init(slint::PhysicalSize({ BSP_LCD_H_RES, BSP_LCD_V_RES }), panel_handle,
                                       touch_handle, buffer);
    /* Instantiate the UI */
    auto ui = AppWindow::create();
    /* Show it on the screen and run the event loop */
    ui->run();
}

The resulting rendering at https://components.espressif.com/components/slint/slint/versions/1.2.0~1 however escapes various characters wrongly and changes casing.

For example #include <bsp/display.h> becomes this:

Or static std::vector<slint::platform::Rgb565Pixel> buffer(BSP_LCD_H_RES * BSP_LCD_V_RES); becomes this:

Note how the letter casing changed wrongly.

bsp_display_new(&bsp_disp_cfg, &panel_handle, &io_handle); becomes this:

And finally ui->run(); becomes this:

The unfortunately consequence of the mis-rendering is that users who are trying to follow the steps by copy & paste find their project not compiling and having to fix up the source code by hand.

To Reproduce

The reproduce, just open https://components.espressif.com/components/slint/slint/versions/1.2.0~1 and compare the rendering with the source at https://github.com/slint-ui/slint/blob/v1.2.0/api/cpp/esp-idf/slint/README.md

Expected behaviour

I expected the rendering of code fences to retain the exact C++ code formatting, so that it can be copy & pasted.

Additional info

No response

I have checked existing issues and online Documentation

• [X] I confirm I have checked existing issues and online Documentation.

[kumekay]

@tronical Thank you for opening this issue. It really looks like a bug, we will address it.

Even though markdown is relatively simple format, it's poorly standardised and making it render "just like GitHub does" is not so trivial task, but hope eventually we will be able to cover all edge cases.

[tronical]

Thanks for looking into this. I'd be happy to work around this in our README in any way possible. We don't need GitHub-like rendering, just a a plain code fence.

Is there a way of working around it? Are you using a markdown renderer that I could run locally to verify how to escape the characters on our end so that the code fence works?

[kumekay]

@tronical Unfortunately I'm not aware of workaround right now, we will investigate the issue next week and let you know. I'm pretty sure no action will be required from you to make it render correctly.

We are planning to add a command to preview documentation locally before committing, but it's not available yet.

Markdown rendered in few passes. I suppose this behaviour is a side effect either of mermaid diagrams or MathJax equations

[kumekay]

@tronical The issue was fixed on the server, now code snippets are rendered correctly

https://components.espressif.com/components/slint/slint/versions/1.2.0~1

[tronical]

Thank you ❤️