lvgl/docs/src/contributing/writing_docs.mdx

---
title: Writing Docs
description: "How to author LVGL documentation in MDX — formatting rules, sidebar ordering, and the full component catalog."
---

LVGL documentation is authored in **MDX** (Markdown + JSX). Pages live under `docs/src/` and the directory structure drives the URL. This page is the full reference for authors; the top-level `docs/README.md` is the quick start.

## Page Basics

Every page is a `.mdx` file with YAML frontmatter:

```mdx
---
title: Animations
description: Animate widget properties over time with the LVGL animation engine.
---

# Animations

Animations change a property's value over a period of time...

<LvglExample name="lv_example_anim_1" path="anim/lv_example_anim_1" />
```

- `title` — appears in the sidebar, the browser tab, and as the page's default heading.
- `description` — short summary used in cards, search results, and social previews.


## Formatting

- **Headings** use standard Markdown (`#`, `##`, `###`).
- **Emphasis** is `*italic*` / `**bold**`. Markdown tables and GFM (task lists, strikethrough) are enabled.
- **Unicode** is supported directly — type `°`, `→`, `µ`, etc.
- **Internal links** are root-relative Markdown links rooted at `docs/src/`, e.g. `[Flex](/common-widget-features/layouts/flex)`.
- **API references** use the `<ApiLink>` component instead of raw Markdown links.
- **Images** go under `docs/src/_static/images/` and are referenced via `<Figure src="/_static/images/..." />`.
- **Code blocks** are triple-backtick fenced with a language tag:

  ````mdx
  ```c
  lv_obj_t * btn = lv_button_create(lv_screen_active());
  ```
  ````


## Sidebar Ordering with `meta.json`

Each directory may contain a `meta.json` file that sets the sidebar title and the order of its pages. Without it, pages are listed alphabetically.

```json
{
  "title": "Getting Started",
  "pages": [
    "introduction",
    "quick-overview",
    "platforms",
    "micropython"
  ]
}
```

- `title` — the label shown for the directory in the sidebar.
- `pages` — file/folder names (no extension) in the order they should appear. Any page not listed is appended after the listed ones.


## Components You Can Use in MDX

These components are registered globally by the docs site — you do **not** import them in `.mdx`, just use the JSX tag.

### Structure / layout

| Component | Purpose |
| --------- | ------- |
| `<Card>`, `<Cards>` | Grid of navigation cards. Used on index pages. |
| `<Step>`, `<Steps>` | Numbered walkthroughs / tutorials. |
| `<Tab>`, `<Tabs>` | Tabbed content (e.g. platform-specific instructions). |
| `<Callout type="info\|warn\|error" title="...">` | Admonitions / notes / warnings. |
| `<Collapsible title="...">...</Collapsible>` | Disclosure block for long optional content. |
| `<DirectoryIndex />` | Auto-generated list of child pages for the current directory. |
| `<IndexCards items={[{ title, href, description }]} />` | Card grid generated from a data array. |
| `<ConceptCard>`, `<ConceptCards>` | Cards for conceptual overview sections. |
| `<SmartCard>` | Richer link card with icon + description. |
| `<Figure src="..." alt="..." caption="..." border={false} />` | Image with caption and sizing. |
| `<Kbd>`, `<KbdGroup>` | Keyboard-key styling (e.g. `<Kbd>Ctrl</Kbd>+<Kbd>K</Kbd>`). |
| `<CustomIcon name="..." />` | Renders an LVGL-specific icon from the shared icon set. |

### LVGL examples

| Component | Purpose |
| --------- | ------- |
| `<LvglExample name="..." path="..." />` | Embeds a runnable example: live simulator (when available), the `.c` source, and a GitHub link. The primary way to showcase code. |
| `<LvglExampleBrief>...</LvglExampleBrief>` | One-line summary placed above the detailed description of an example. |

### API references

| Component | Purpose |
| --------- | ------- |
| `<ApiLink name="lv_label_create" display="lv_label_create(parent)" />` | In-line link to an API symbol (function, type, macro, enum). `display` is optional. |
| `<ApiLinkList items={["lv_label", "lv_obj_property_names"]} />` | Placed at the end of a page to link out to the full API pages for related headers. |
| `<ApiMember>`, `<ApiSummary>`, `<ApiTabs>`, `<ApiTab>` | Render function/type members on generated API pages. Rarely hand-authored. |
| `<CallbackSignature>` | Formats a callback function signature block. |
| `<TypeUsedBy>` | Lists callers/users of a given type on API pages. |
| `<ModuleOverview>...</ModuleOverview>` | Wraps the "Header / Functions / Types" summary table at the top of a module page. |
| `<FileIncludes>` | Shows the list of headers / source files that contribute to a module. |
| `<RelatedHeaders>` | Inline list of sibling headers on API pages. |
| `<SourceLink>` | "View source on GitHub" link for the current page / symbol. |

### Widgets & styles

| Component | Purpose |
| --------- | ------- |
| `<StyleProperty name="width" default="..." inherited="..." layout="yes/no" ext_draw="...">` | The standardized "style property" info box used across widget style docs. |
| `<FAQSection>` | Renders Q&A blocks on FAQ pages. |

### Icons

Only a limited set of icons is available for inline use. Use any of the following as a JSX tag — anything outside this list will not render:

- `FileCode`
- `Code`
- `Cloud`
- `Terminal`
- `Palette`
- `Download`
- `Keyboard`
- `Layout`
- `Info`
- `FileText`
- `BookOpen`
- `Sparkles`
- `Box`
- `Blocks`
- `Eye`
- `Hash`
- `Zap`
- `Monitor`
- `Image`
- `Cpu`
- `Server`
- `Link`
- `TestTube`
- `Globe`
- `Figma`