Starlight: "Supported Boards" and "Supported CPUs" Known Issues

[LasseRosenow]

The Supported Boards and Supported CPUs feature in Starlight is still fairly experimental and involves a lot of manual parsing that can easily break considering the extremely un-standardized nature of doxygen markdown. In this issue we aim to collect all the currently known issues, in hopes that one day we might fix all of them and potentially permanently switch the boards lookup onto Starlight.

• Some tables don't get parsed correctly, see: https://guide.riot-os.org/boards/esp32c6-devkit/
• Some pinout images are missing see: https://guide.riot-os.org/boards/nucleo-f207zg/ : treewide: Fix links in the docs and cleanup many boards #22257
• Some code blocks use the wrong language name style, e.g. {.mk} for a Makefile: boards/*: fix (some) Starlight build issues in doc.md files #22243
• Some boards are missing the doc.md file: boards: add missing doc.md files #22221
• References don't work, see: https://guide.riot-os.org/boards/esp32-heltec-lora32-v2/ see section esp32_mcu_esp32 “MCU ESP32”.
• The @author and \section commands are not interpreted, see: https://guide.riot-os.org/boards/esp32-heltec-lora32-v2/ Support for Heltec WiFi LoRa 32 V2 boards @author Gunar Schorcht [gunar@schorcht.net](mailto:gunar@schorcht.net) \section esp32_heltec_lora32_v2 Heltec WiFi LoRa 32 V2
• The @image commands are not resolved correctly if they go to an external page, see https://guide.riot-os.org/boards/esp32-heltec-lora32-v2#overview :treewide: Fix links in the docs and cleanup many boards #22257
• Newline control characters \n are not parsed correctly but printed as text. Perhaps replace them in the parser to <br>?: treewide: Fix links in the docs and cleanup many boards #22257
• Update porting cpu and porting boards guide with information on the constraints for what markdown syntax is allowed:
  • manually built Table of Contents are not supported anymore
  • Only use markdown section references etc.
  • Images have to use either the HTML tag or the markdown syntax
  • Newlines have to be written with
    instead of \n
  • The backticks are preferred over any other Code section syntax
  • (once we have fully migrated: don't do any doxygen syntax at all)
  • Only allow the markdown ### section syntax and don't document title single # headings.

[crasbe]

There are some additional warnings printed for which I added two new tasks in your initial post.

14:47:15 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.mk}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:15 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.mk}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
Tried to load documentation for board "bastwan" but it doesn't contain a doc.md file, skipping...
14:47:17 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:17 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:17 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:17 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:17 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:17 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:17 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
14:47:18 [WARN] [astro-expressive-code] Error while highlighting code block using language "{.c}" in markdown/MDX document. The language could not be found. Using "txt" instead. Ensure that all required languages are either part of the bundle or custom languages provided in the "langs" config option.
Tried to load documentation for board "frdm-kl43z" but it doesn't contain a doc.md file, skipping...
Tried to load documentation for board "hifive1" but it doesn't contain a doc.md file, skipping...
Tried to load documentation for board "hifive1b" but it doesn't contain a doc.md file, skipping...
Tried to load documentation for board "samr30-xpro" but it doesn't contain a doc.md file, skipping...
Tried to load documentation for board "slwstk6000b-slwrb4150a" but it doesn't contain a doc.md file, skipping...
Tried to load documentation for board "slwstk6000b-slwrb4162a" but it doesn't contain a doc.md file, skipping...
Tried to load documentation for board "ublox-c030-u201" but it doesn't contain a doc.md file, skipping...

[crasbe]

• Some tables don't get parsed correctly, see: https://guide.riot-os.org/boards/esp32c6-devkit/

This is caused by the <center> tags. Starlight does not interpret it as a table anymore. Perhaps this is a bug?

[crasbe]

• Some tables don't get parsed correctly, see: https://guide.riot-os.org/boards/esp32c6-devkit/

This is caused by the <center> tags. Starlight does not interpret it as a table anymore. Perhaps this is a bug?

It's not a Starlight/Astro bug, when creating an .mdx file with the following content, the table is rendered (although the center tags are ignored):

---
title: Table in Center Tags
description: Minimal example to showcase the bug
---

## Non-working table inside of center tags

<center>
Column 1 | Column 2 | Column 3
:--------|:---------|:--------
Row 1    | Row 1    | Row 1
Row 2    | Row 2    | Row 2
</center>

## Working table outside of center tags

Column 1 | Column 2 | Column 3
:--------|:---------|:--------
Row 1    | Row 1    | Row 1
Row 2    | Row 2    | Row 2

---

I tried to look at the JavaScript stuff on how this is converted, but my brain just melted. This is not for me, sorry.