@lvgl/examples-generator

Generate fumadocs-compliant MDX pages from a tree of LVGL C example files annotated with Doxygen blocks.

Input: a directory tree of .c files (each with a /** @title ... */ block) and about.md files describing folder structure.

Output: a mirror tree of index.mdx + meta.json folders and <slug>.mdx leaf pages, ready to drop into a fumadocs content/ directory.

Requirements

• Node.js ≥ 18 (uses util.parseArgs and native fetch).

Install

One-shot (CI-style):

npx -p @lvgl/examples-generator lvgl-examples-gen --src path/to/examples --out path/to/content

Project-local:

npm install --save-dev @lvgl/examples-generator

Once installed, the three bins are directly on PATH inside scripts: lvgl-examples-gen, lvgl-examples-check-about, lvgl-examples-check-examples.

CLIs

Three binaries ship with the package. All three take --src <path> and exit non-zero on hard errors.

lvgl-examples-check-about

Validate every about.md under --src parses and has a title field.

npx -p @lvgl/examples-generator lvgl-examples-check-about --src examples

Exit codes: 0 all good · 1 validation error · 2 usage error.

lvgl-examples-check-examples

Scan every .c file under --src and report Doxygen annotation coverage.

npx -p @lvgl/examples-generator lvgl-examples-check-examples --src examples [--list-skipped]

Rules:

• File with no @title block → skipped (not an error). Used for helper .c files that shouldn't appear in docs.
• File with two or more @title blocks → error. Exactly one is expected.
• File with @title but missing @brief or description body → warning, not an error.

Flags:

• --list-skipped — print each skipped file's path.

Exit codes: 0 no errors (warnings allowed) · 1 at least one error · 2 usage error.

lvgl-examples-gen

Build the MDX tree.

npx -p @lvgl/examples-generator lvgl-examples-gen --src examples --out content/docs/examples

Requires --src/about.md to exist (it becomes the landing page). Exit codes: 0 success · 1 failure · 2 usage error.

Doxygen block format

Each .c file that should appear in docs needs a Doxygen block starting with @title:

/**
 * @title Arc with a gradient
 * @brief Draw an arc and fill it with a gradient.
 *
 * Creates a circular arc using `lv_arc_create` and applies a radial
 * gradient style. Demonstrates the interplay of arc width and gradient
 * direction.
 */

void lv_example_arc_1(void)
{
    /* ... */
}

Recognized tags:

| Tag | Required | Meaning | |---|---|---| | @title | yes | Page/section heading. | | @brief | no | One-liner rendered under the heading. | | (body) | no | Free-form Markdown shown below @brief. | | @hide_in_docs | no | If present, the example is excluded from output. |

about.md frontmatter

Each folder that should render as a page needs an about.md. Markdown body is prepended above the examples on that page.

---
title: Arcs
description: Circular arc widgets with styling.
order: 20
flatten: false
directory_index: true
---

Arcs are a circular widget for visual indicators and progress displays.

Fields:

| Key | Type | Default | Meaning | |---|---|---|---| | title | string | — | Required. Page title + sidebar label. | | description | string | — | Page-level summary (fumadocs frontmatter). | | order | number | — | Sibling sort order. Lower first. Omit for alphabetical. | | flatten | boolean | false | If true, this folder is merged into its parent page — its examples render inline under the parent's heading, not as a separate route. Propagates to descendants. | | directory_index | boolean | true | If true, a <DirectoryIndex /> component is appended to the page listing child pages. |

Any extra keys are passed through to the MDX frontmatter unchanged.

Output shape

Given this input:

examples/
  about.md
  widgets/
    about.md
    arc/
      about.md
      lv_example_arc_1.c
      lv_example_arc_2.c
    bar/
      about.md
      lv_example_bar_1.c

The generator emits:

content/docs/examples/
  index.mdx        ← from examples/about.md
  meta.json
  widgets/
    index.mdx      ← from widgets/about.md (+ inline groupings)
    meta.json
    arc.mdx        ← from arc/about.md + its .c files
    bar.mdx        ← from bar/about.md + its .c files

• Folders with child pages emit index.mdx + meta.json + a subdirectory.
• Leaf folders emit a flat <slug>.mdx.
• flatten: true folders merge their examples into the parent's MDX as ## inline groupings.
• meta.json includes a pages array excluding "index" so a sidebar click on the folder routes to the index page.

Programmatic use

import { discover, emitTree } from '@lvgl/examples-generator';

const tree = discover('/abs/path/to/examples');
emitTree(tree, { outDir: '/abs/path/to/content/docs/examples' });

License

MIT