# Writing Docs (/contributing/writing_docs)
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 [#page-basics]
Every page is a `.mdx` file with YAML frontmatter:
```mdx title="mdx" lineNumbers=1
---
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...
```
* `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 [#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 plain relative Markdown links, e.g. `[Flex](../layouts/flex)`.
* **API references** use the `` component instead of raw Markdown links.
* **Images** go under `docs/src/_static/images/` and are referenced via ``.
* **Code blocks** are triple-backtick fenced with a language tag:
````mdx title="mdx" lineNumbers=1
```c
lv_obj_t * btn = lv_button_create(lv_screen_active());
```
````
Sidebar Ordering with `meta.json` [#sidebar-ordering-with-metajson]
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="json" lineNumbers=1
{
"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 [#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 [#structure--layout]
| Component | Purpose |
| ------------------------------------------------------------- | ------------------------------------------------------------- |
| ``, `` | Grid of navigation cards. Used on index pages. |
| ``, `` | Numbered walkthroughs / tutorials. |
| ``, `` | Tabbed content (e.g. platform-specific instructions). |
| `` | Admonitions / notes / warnings. |
| `...` | Disclosure block for long optional content. |
| `` | Auto-generated list of child pages for the current directory. |
| `` | Card grid generated from a data array. |
| ``, `` | Cards for conceptual overview sections. |
| `` | Richer link card with icon + description. |
| `` | Image with caption and sizing. |
| ``, `` | Keyboard-key styling (e.g. `Ctrl+K`). |
| `` | Renders an LVGL-specific icon from the shared icon set. |
LVGL examples [#lvgl-examples]
| Component | Purpose |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `` | Embeds a runnable example: live simulator (when available), the `.c` source, and a GitHub link. The primary way to showcase code. |
| `...` | One-line summary placed above the detailed description of an example. |
API references [#api-references]
| Component | Purpose |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `` | In-line link to an API symbol (function, type, macro, enum). `display` is optional. |
| `` | Placed at the end of a page to link out to the full API pages for related headers. |
| ``, ``, ``, `` | Render function/type members on generated API pages. Rarely hand-authored. |
| `` | Formats a callback function signature block. |
| `` | Lists callers/users of a given type on API pages. |
| `...` | Wraps the "Header / Functions / Types" summary table at the top of a module page. |
| `` | Shows the list of headers / source files that contribute to a module. |
| `` | Inline list of sibling headers on API pages. |
| `` | "View source on GitHub" link for the current page / symbol. |
Widgets & styles [#widgets--styles]
| Component | Purpose |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `` | The standardized "style property" info box used across widget style docs. |
| `` | Renders Q\&A blocks on FAQ pages. |
Icons [#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`