Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI
Writing BUI's docs
This is the guide for everyone writing pages for the BUI website. Read it once before your first page; keep the cheat-sheet open while you write.
The four pages already written set the bar. Read them first, and copy their shape:
src/content/docs/start/introduction.mdx: a concept pagesrc/content/docs/start/installation.mdx: a task page with<LangTabs>src/content/docs/tutorials/first-app-python.mdx: a tutorial with<Steps>src/content/docs/project/roadmap.mdx: a status page with<StatusTable>
1. Who we're writing for
From newcomers to experts, on the same page:
- Newcomers may never have used Blender, a UI toolkit or a terminal much. They need the first two paragraphs to make sense on their own, and every new term defined the first time it appears.
- Experienced developers skim. They need headings that say what's in the
section, code they can copy, and exact names (
NumberSlider,BUI_GPU=1). - Experts want limits and edge cases. Put them in their own section ("Limitations", "How it works") near the end, not sprinkled through the tutorial.
When the two pull apart, write the main path for the newcomer and link the expert to the detail.
Per-language pages: one language, one reader
Pages that belong to one language (tutorials/first-app-*,
tutorials/tkinter-app, python/*, rust/*, javascript/*, imgui/*,
c/*) are read by someone who knows only that language and is coming
from it.
- Explain concepts in that language's own terms and idioms.
- No comparisons with other languages or their libraries ("like React's
useState", "unlike Python…", "the same as the Rust crate"). No cards that send the reader to another language's page. - Don't assume knowledge of other ecosystems. A Rust page may mention Rust crates (gpui, Leptos, taffy); a Python page may mention tkinter and Qt. Dear ImGui pages may map from ImGui's C++ names, because that's how ImGui's own docs are written.
- Shared pages (
start/,concepts/,reference/,performance/,project/) may compare languages.
Rust: both syntaxes, always
BUI's Rust crate has two first-class syntaxes: rsx! (HTML-like
markup, components and hooks) and gpui builders (div().flex().gap_2() .child(...), Render, cx.listener, state in the view's fields). Wherever
a Rust page shows a UI example, show both, side by side:
<Tabs sync="rust-syntax" label="Rust syntax">
<Tab label="rsx!">
```rust
rsx! { <div flex gap-2>"Hi"</div> }
```
</Tab>
<Tab label="gpui builders">
```rust
div().flex().gap_2().child("Hi")
```
</Tab>
</Tabs>
Always use exactly these labels and sync="rust-syntax", so the reader's
choice carries across pages. Never present the builder syntax as a
footnote or an "advanced" alternative. Say "HTML-like markup" for rsx!,
not "JSX".
Rust is on crates.io
blenderui is published on crates.io: install with cargo add blenderui.
Never write "not published yet" or tell readers to use a git dependency for
it. The same goes for blenderui-imgui: cargo add blenderui-imgui.
No recaps, no emoji
- No
<Recap>blocks. End a page with next-step cards only. - No emoji anywhere in content (no checkmarks, colored dots, test
tubes, arrows-as-emoji). For status, use
<StatusTable>status keys (done,partial,experimental,planned),<Badge>, or plain words ("Works", "Partial", "Experimental"). The components draw the icons.
Demo tricks: once, and only where they're true
Drag-to-scrub, undo and typing 2*pi into a field are
BUI's party tricks. Mention each at most once per page, and only where
it's relevant. Typed math works only in Blender number fields and
sliders (Blender components, tkinter Spinbox / Scale, QSlider,
form controls inside styled, ImGui's Blender-widgets build). Never imply
it works in plain text inputs: an HTML <input> outside styled,
tkinter's Entry, QLineEdit or ImGui's InputText.
2. Voice
Warm, confident, precise. Like a friend who knows the code well and is happy you're here.
- Second person, active voice. "Drag the slider", not "the slider can be dragged". "BUI redraws only the widget", not "only the widget is redrawn".
- Short sentences. One idea each. If a sentence has two commas and an "and", split it.
- Plain words. "Use", not "utilize". "Start", not "initialize" (unless it's the API's name).
- Define terms on first use, in the same sentence: "the kit, BUI's runtime written in C, …". Add new terms to the glossary page.
- Lead with what the reader gets, then how. "You get Blender's color picker: click the swatch." not "ColorSwatch opens a picker on click."
- Be honest about status. If something is partial, say so in the first
place the reader would trip over it. Never imply something works when it
doesn't. Unbuilt features get
<ComingSoon />(see below). - Never invent numbers. Every number (timings, counts, sizes) must come from the repository, with the same rounding. Benchmarks come with their context (machine, renderer, what was measured). If you can't find a source, leave the number out.
- No fake quotes, testimonials or users.
- Headings are sentence case, no trailing period: "Drag across checkboxes", not "Drag Across Checkboxes."
- Write "BUI" for the project,
blenderuifor the Python and Rust package names, and@blender-ui/react/@blender-ui/nativefor npm. In Python code, importblenderui(notbui): it's the published name. - Keyboard keys use
<Kbd>: Ctrl,<Kbd keys="Ctrl+Shift+Z" />. Write "Ctrl" (not "Control" or "^") and add "(Cmd on macOS)" only where it's true.
Jokes
One gentle joke per page, at most, and it's optional. Put it in
<Callout type="joke"> or a short aside in the text. Good jokes are about
Blender culture (the default cube, pressing Q, render noise) or
about software. Never about the reader, their skill, other projects or
people. If you have to explain it, cut it.
3. Page template
Copy this into a new .mdx file and fill it in:
---
title: Number fields and sliders # sentence case, no period
description: One sentence that says what the reader will get from this page.
section: Concepts # one of the sections in src/config/nav.ts
order: 30 # position in the section; leave gaps
status: stable # stable | preview | coming-soon
languages: ["python", "rust"] # optional: python rust javascript c cpp imgui
badges: ["Windows only"] # optional, short
sources: ["docs/components.md", "kit/intern/kit_widgets.c"] # repo files you checked
---
A hook: one or two sentences that tell the reader why this matters to them,
in their terms. What will they be able to do after reading?
## First section
Plain explanation, then a small, runnable example.
## …
## Next steps
<CardGrid>
<Card title="…" href="docs/…/" icon="arrow-right">One sentence.</Card>
</CardGrid>
Rules of thumb:
- The hook is the first lines, before any heading. No "In this page we will…". Say what the reader gets.
- Examples are small and runnable. Copy-paste into a file and run. Show
the imports. Prefer 5 to 25 lines. Give the file a name with
title=. - Every page ends with next-step cards (two to four). No
<Recap>. - Length: tutorials can be long; guides should be skimmable; reference
pages are tables. Split a page when it has more than about eight
##sections. - Don't repeat other pages. Link to them. The installation page owns installation; the reference pages own full tables.
4. Adding a page or a section
Add a page: create one .mdx file under src/content/docs/<folder>/.
That's all. The sidebar, breadcrumbs, previous/next links, search index and
"Soon" badges are generated from the frontmatter. The URL follows the path:
src/content/docs/rust/hooks.mdx → /docs/rust/hooks/.
sectiondecides the sidebar group (the folder is just for tidiness; keep them matching).orderdecides the position inside the group (ties sort by title).draft: truekeeps a page out of the build while you work on it.- The build fails if the frontmatter doesn't match the schema in
src/content.config.ts, so typos insectionare caught for you.
Add a section: add an entry to sections in src/config/nav.ts, in the
order it should appear. Nothing else changes.
Components need no imports. Every component in src/components/docs/ is
available in every .mdx page.
Links between pages: in Markdown, use relative links with a trailing
slash: from /docs/start/installation/, write
[the tutorial](../../tutorials/first-app-python/). In <Card href>, use the
site path without a leading slash: href="docs/tutorials/first-app-python/".
Both keep working if the site moves to a sub-path.
Check your work:
pnpm dev # http://localhost:4321, live reload
pnpm build # must finish with no errors or warnings
pnpm check # type-checks components and frontmatter
5. Component cheat-sheet
All components live in src/components/docs/ and are documented at the top
of each file.
Callout
<Callout type="tip">Hold Shift while dragging for fine control.</Callout>
<Callout type="warning" title="Windows only">The npm packages are prebuilt for Windows x64.</Callout>
<Callout type="joke">BUI is Blender's UI, minus the default cube.</Callout>
type: note (default), tip, warning, joke, coming-soon. Optional
title. One or two per page; if everything is a callout, nothing is.
ComingSoon
For features that aren't built yet. It links to the roadmap and to GitHub issues.
<ComingSoon feature="WebAssembly" />
<ComingSoon feature="Per-glyph font fallback">
Characters missing from Inter show as boxes for now. Blender's BLF fallback is next.
</ComingSoon>
Works on Linux and Windows; macOS GPU rendering is <ComingSoon inline />.
If a whole page describes something unbuilt, also set status: coming-soon
in the frontmatter: the sidebar shows "Soon" and the roadmap lists it.
LangTabs, Tabs and Tab
<LangTabs> remembers the reader's language across pages. Use the labels
Python, Rust, JavaScript, C, C++, Dear ImGui so the choice carries over.
Leave blank lines around Markdown inside a <Tab>.
<LangTabs>
<Tab label="Python">
```py
bui.set_gpu(True)
```
</Tab>
<Tab label="Rust">
```rust
Application::new().gpu(true)
```
</Tab>
</LangTabs>
<Tabs> is the same without the language memory; <Tabs sync="pkg">
syncs all tab groups with the same key (for example npm / pnpm / bun). Don't
nest tabs.
Steps
Wrap a normal numbered list. Each step starts with a bold sentence that says what to do.
<Steps>
1. **Install BUI.**
```sh
pip install blenderui
- Run the demo.
The bold first sentence becomes the step's title: it stays pinned under the header while the reader is in that step, and a rail fills as they go. Keep it short (one line).
Figure
<Figure
src="images/qt.png"
alt="A Qt-syntax form on BUI: text field, dropdown, slider and buttons"
caption="Qt syntax, drawn by BUI (<code>examples/qt_syntax_demo.py</code>)"
width={520}
height={222}
/>
alt says what's in the picture; caption says why it matters. width and
height are read from the file when you leave them out. variant="bleed"
drops the hatched stage for wide images.
Light and dark screenshots. The reader sees the one that matches the site's theme:
<Figure light="images/shots/qt-form-light.png" dark="images/shots/qt-form-dark.png" alt="…" />
<Figure shot="qt-form" src="images/qt.png" alt="…" /> {/* the pair from images/shots/, src until it exists */}
<ThemedImage shot="qt-form" fallback="images/qt.png" alt="…" /> {/* the bare image, no frame */}
Charts: BenchChart, BarChart, GroupedBarChart, LineChart
Every published benchmark number lives in src/data/bench.ts (copied from
README.md "Performance"). Use it instead of retyping numbers:
<BenchChart id="first-frame" /> {/* chart + "Open bench" with the exact table */}
<BenchTable id="startup" /> {/* just the exact table */}
Chart ids: first-frame, idle-all, start-time, start-cpu, idle-cpu,
memory-start, start-all, fps, cpu-per-frame, ram,
cpu-per-frame-cells, uncapped-fps, frame-times, js-first-frame,
js-cpu-3000. Table ids: startup, cells3000, cellsFull, frameTimes,
jsStartup, jsAnim3000, jsAnim1000, plus one-language views for per-language
pages: startupGpui (the same gpui code only), jsStartupJs, jsAnim3000Js,
jsAnim1000Js (no Rust rows). Optional title, subtitle, plain (no headline
number) and table (a different table id under "Open bench").
Your own numbers (still from the repository, with their source):
<BarChart
title="Wheel size" unit="MB" better="lower"
bars={[
{ label: "blenderui", value: 4.2, ours: true },
{ label: "PySide6", value: 180 },
]}
/>
<GroupedBarChart title="…" unit="ms" series={[{ name: "CPU", ours: true }, { name: "GPU" }]}
groups={[{ label: "Rust", values: [38, 42] }]} />
<LineChart title="…" unit="fps" x={[100, 1000, 3000]} xLabel="cells"
lines={[{ name: "GPU", ours: true, values: [1491, 309, 94] }]} />
ours: true draws BUI's bars in Blender blue; the rest are hatched grey with
an automatic "N× more" note. Add table={{ caption, columns, rows }} for an
"Open bench" disclosure.
StatusTable
<StatusTable rows={[
["tkinter syntax", "done", "Every public name: 7,846 of 7,846"],
["Qt syntax", "partial", "About 25% of the main classes' methods"],
["macOS host", "experimental", "Written, not yet run on a Mac"],
["WebAssembly", "planned", "The kit in a <code><canvas></code>"],
]} />
Status: done, partial, experimental, planned (the component draws
the icon and label; never type emoji yourself). Optional
columns={["Feature", "Status", "Notes"]}, legend={false}.
CardGrid and Card
<Recap> still exists as a component, but don't use it: pages have no
recaps.
<CardGrid>
<Card title="Hooks" href="docs/rust/hooks/" icon="layers" kicker="Rust">use_state, signals and effects.</Card>
<Card title="egui" soon>BUI panels inside egui.</Card>
</CardGrid>
<CardGrid cols={3}> for three columns. Card icons: any
Phosphor name (rocket-launch, gauge,
file-py, terminal-window …) or a short alias (terminal, book,
sparkles, flag, layers, zap, cpu, monitor, undo, github).
A misspelled name fails the build. The same icons work inline:
<Icon name="flask" weight="duotone" />.
Compare
<Compare left="Standard tkinter" right="On BUI">
<div slot="left">
Text, code or a `<Figure />`.
</div>
<div slot="right">
The other side.
</div>
</Compare>
Kbd, Badge, Hatch, PageStatusList
Press <Kbd>Q</Kbd>, or <Kbd keys="Ctrl+Shift+Z" />.
<Badge>New</Badge> <Badge tone="preview">Preview</Badge> <Badge tone="soon">Soon</Badge>
<Hatch /> {/* a divider between big parts of a long page */}
<PageStatusList status="coming-soon" /> {/* pages by status, from the collection */}
Code blocks
Code blocks use Expressive Code: copy buttons, light and dark themes, and these extras:
```py title="app.py" {3} ← file name tab, line 3 highlighted
```rust ins={2} del={1} ← added / removed lines
```sh frame="terminal" title="PowerShell" ← a terminal window
```js "useState" ← highlight a word
Use py, rust, js/jsx/ts, c, cpp, cmake, toml, sh (for
commands; no $ prompts), text for output.
Tables
Plain Markdown tables. They get borders and scroll sideways on phones. Align
numbers right with | ---: |.
6. Images
- Screenshots of BUI come from the repository:
docs/images/*.png, regenerated bypython tools/gen_doc_images.py. Copy the ones you use intowebsite/public/images/with the same file name, and reference them asimages/<name>.png. - Don't edit, crop or upscale screenshots; they show real pixels. Never present a mock-up as a screenshot. If no screenshot exists, say so, or ask for one in your PR.
- Diagrams: prefer a short list or table. If you need a picture, use an
inline SVG in the site's colors (
currentColor,var(--primary)), with text in the SVG for accessibility. - File names: lowercase, dashes, what it shows:
rust-forms.png. - Keep PNGs under about 200 KB.
Images available now in public/images/: c-kit-hello.png, components.png,
components-layout.png, components-nodes.png, components-values.png,
components-views.png, first-app-python.png, imgui-blender.png,
imgui-python-hello.png, imgui-python-hello-blender.png, imgui-stock.png,
qt.png, qt-export.png, qt-gauge.png, react-counter.png,
rust-forms.png, rust-hello.png, rust-showcase.png, tkinter_canvas.png,
tkinter_items.png, tkinter_messagebox.png, tkinter_notes.png,
tkinter-render-settings.png. New screenshots go in public/images/shots/ as -dark.png / -light.png pairs,
listed in public/images/shots/INDEX.md. They're rendered at 2x and shown at
half their pixel size.
Show the result. Wherever a page shows a UI result, add a
<Figure>with a real screenshot. If none exists yet, leave a placeholder comment for the image pass, naming the file and what it must show:{/* IMAGE: shots/<area>-<name>-dark.png — what it should show */}
7. Getting the facts right
The repository is the source of truth; the website explains it. Before you write a claim, find it.
- Start with the existing guides:
README.md,docs/*.md,INTEGRATION.md,ARCHITECTURE.md,CHANGELOG.md,bindings/imgui/README.md,bindings/imgui/blender/README.md,bindings/rust/bench/README.md,SYNTAX_COVERAGE.md. - Check names against the code: Python in
bindings/python/bui/, Rust inbindings/rust/*/src/, JavaScript inbindings/node/andbindings/react/, the C API inkit/include/BUI_kit.h, CMake options inCMakeLists.txt, Python packaging inpyproject.toml. - Prefer runnable examples from
examples/and the tests. The tests (bindings/python/tests/,bindings/rust/*/tests/,tests/) show real, working usage. - List what you checked in the
sources:frontmatter. They appear as links at the bottom of the page, so readers (and the next writer) can verify. - When the docs disagree with the code, the code wins. Note the
mismatch in your PR. Known ones so far:
docs/rust.mdsays Rust 1.85;bindings/rust/Cargo.tomlsaysrust-version = "1.88". The site says 1.88.docs/publishing.mdsays Linux wheels use the Tk window;pyproject.tomlnow installs the X11 headers for cibuildwheel, so Linux wheels get the native host (asREADME.mdsays).
- Don't run heavy builds to check a claim (no parallel C or Rust builds; the maintainers' machine doesn't like it). Read the code instead.
8. Planned pages
About 50 pages, grouped by section. Claim one by opening an issue or a
draft PR titled docs: <path>, then write it. Keep the file path, so links
from other pages keep working. Orders leave gaps for later pages.
Already written: start/introduction, start/installation,
tutorials/first-app-python, project/roadmap.
Tutorials (src/content/docs/tutorials/)
| File | Order | Scope |
|---|---|---|
tkinter-app.mdx |
20 | Run an existing tkinter app unchanged (blenderui-tk, install(), import by name), then use the Blender look (LabelFrame as panels, Spinbox as number fields). Sources: docs/tkinter.md, examples/tk_unchanged_app.py |
first-app-qt.mdx |
30 | A small Qt-syntax form: QApplication, layouts, signals, a slider driving a progress bar. Be upfront that Qt is partial. Sources: docs/qt.md, examples/qt_syntax_demo.py |
first-app-rust.mdx |
40 | The hello.rs counter in both syntaxes: rsx! with a #[component], use_state and Tailwind attributes, and gpui builders with state in the view; a <NumberSlider>. Sources: docs/rust.md, bindings/rust/blenderui/examples/hello.rs |
first-app-react.mdx |
50 | A React counter on Node or Bun, signals in JSX, then bui build to a 5 MB executable. Sources: docs/javascript.md, bindings/react/examples/counter.jsx |
first-app-imgui.mdx |
60 | Dear ImGui's demo on BUI from Python and C++, then the Blender-widgets build. Sources: docs/imgui.md, examples/imgui_demo.cpp |
first-app-c.mdx |
70 | kit_hello.c line by line: nodes, properties, the packer, the host callback, the window loop. Sources: docs/c-api.md, examples/kit_hello.c |
Python (src/content/docs/python/)
| File | Order | Scope |
|---|---|---|
tkinter.mdx |
10 | tkinter compatibility: the three ways in, module map, what you get, the Blender look, behaviour notes, limitations, testing your app against stdlib tkinter. Source: docs/tkinter.md |
qt-syntax.mdx |
20 | Qt syntax: how it maps, supported classes, signals, layouts, custom painting with QPainter, coverage (~25%) and what's missing. Source: docs/qt.md |
components.mdx |
30 | The Blender components: App, the common API (value, on_change, description, weight), layout with Column/Row/Panel/Split, menus and pie menus. Source: docs/components.md |
components-reference.mdx |
40 | Every component's signature in tables: layout, values, buttons, views, menus, color and editors, node editor and areas. Source: docs/components.md, bindings/python/bui/components/ |
headless-testing.mdx |
50 | Testing Python UIs without a window: render_raster, press/motion/release, pixels, frame budgets. Sources: docs/components.md, bindings/python/tests/test_components.py |
Rust (src/content/docs/rust/)
| File | Order | Scope |
|---|---|---|
rsx-and-components.mdx |
10 | rsx! / view! markup, control flow in markup, #[component] with optional props and key, three component styles (zopra, React, Leptos). Source: docs/rust.md |
hooks.mdx |
20 | use_state, signal, Memo, Effect, context; React, Leptos and zopra spellings; limits (no use_resource yet). Source: docs/rust.md |
html-elements.mdx |
30 | All 113 HTML elements, what they draw like, <details>, lists, tables, inline text. Source: docs/rust.md#elements |
css-and-tailwind.mdx |
40 | <style> sheets, selectors, the cascade, var(), colors, at-rules; Tailwind v4 classes and bare attributes; "did you mean" errors; tw!. Source: docs/rust.md#styling, CHANGELOG.md |
styled-and-blender-components.mdx |
50 | The three looks: plain HTML, styled, and Blender components (Button, Checkbox, NumberSlider …); form controls. Sources: docs/rust.md, examples/forms.rs |
layout.mdx |
55 | Flexbox, grid with named areas, tables, calc(), taffy under the hood. Source: docs/rust.md#layout |
effects-and-animations.mdx |
60 | @keyframes, transitions, filters, backdrop-filter, blend modes, clip-path, masks, 2D transforms. Source: docs/rust.md |
events.mdx |
70 | Listeners, cx.listener, closures without parameters, painting your own content. Source: docs/rust.md#events |
headless-testing.mdx |
80 | Application::headless(), screenshots to PNG, tests. Source: docs/rust.md#headless-rendering-and-tests |
gpui-syntax.mdx |
90 | The gpui-compatible app model (Application, Render, WindowHandle, div().flex()), compiling gpui code unchanged. Sources: docs/rust.md#the-app-model, bindings/rust/bench/common/settings.rs |
JavaScript & React (src/content/docs/javascript/)
| File | Order | Scope |
|---|---|---|
native-api.mdx |
10 | @blender-ui/native: App, windows, createElement, attributes, events, requestAnimationFrame, headless mode. Source: docs/javascript.md#plain-javascript |
react.mdx |
20 | @blender-ui/react: render, JSX setup (jsxImportSource), host components, Blender components, Suspense and transitions. Source: docs/javascript.md#react |
svelte.mdx |
25 | @blender-ui/svelte: render, register (Node.js, Bun), elements and events, Blender components, scoped styles, signals as stores, bui build. Source: docs/javascript.md#svelte |
signals.mdx |
30 | Hooks that hold signals: pass {count} to update one node, read count.value to re-render; the conformance suite. Source: docs/javascript.md#hooks-and-signals |
standalone-executables.mdx |
40 | bui build (QuickJS, ~5 MB), --bun, --console, --dev, bui run. Source: docs/javascript.md#standalone-apps |
Dear ImGui (src/content/docs/imgui/)
| File | Order | Scope |
|---|---|---|
cpp.mdx |
10 | imgui.h + imgui_impl_bui.h, ImGui_ImplBUI_CreateApp, linking bui::imgui. Source: docs/imgui.md#c |
c.mdx |
20 | cimgui.h, all 399 functions, the C app helpers. Source: docs/imgui.md |
python.mdx |
30 | blenderui.imgui, pyimgui-style returns, imgui.run. Source: docs/imgui.md#python |
rust.mdx |
40 | The blenderui-imgui crate, the safe API and the FFI. Source: docs/imgui.md#rust |
blender-widgets.mdx |
50 | BUI_IMGUI_BLENDER_WIDGETS / blender-widgets: what changes, the mapping table, behaviour differences, gaps. Sources: bindings/imgui/blender/README.md |
coverage.mdx |
60 | What's covered per language, what's skipped and why, regenerating the bindings, the Blender style. Sources: docs/imgui.md#coverage, bindings/imgui/README.md |
C & C++ (src/content/docs/c/)
| File | Order | Scope |
|---|---|---|
c-api.mdx |
10 | The kit API: nodes, properties, geometry managers, the context and host, windows, events. Source: docs/c-api.md, kit/include/BUI_kit.h |
embedding.mdx |
20 | BUI drawing inside your own renderer: render sinks, the stable C ABI (api/), the Qt/QPainter backend, PySide, SVG output. Source: INTEGRATION.md |
Concepts (src/content/docs/concepts/)
| File | Order | Scope |
|---|---|---|
how-it-works.mdx |
10 | The layers: your code → bindings → kit → renderer → window. What's ported from Blender. Sources: README.md#how-it-works, ARCHITECTURE.md |
blender-widgets.mdx |
20 | Blender's widgets and interactions in depth: number-field dragging rules, Ctrl snapping, sliders, multi-field drags, drag-toggle, menus, search, undo. Sources: docs/components.md#interactions, CHANGELOG.md |
rendering.mdx |
30 | CPU raster vs GPU (Direct3D 11, OpenGL 3.3): turning it on, pixel parity, memory trade-offs, Slug text. Sources: docs/getting-started.md#gpu-rendering, ARCHITECTURE.md |
damage-rendering.mdx |
40 | Why idle costs nothing: damage rects, tiles, frame pacing. Sources: README.md, ARCHITECTURE.md |
window-hosts.mdx |
50 | Native Win32 / X11 / Cocoa hosts, the Tk fallback (BUI_HOST=tk), headless mode, HiDPI, Linux without X11. Source: docs/getting-started.md#window-hosts |
text-and-fonts.mdx |
60 | Inter embedded, FreeType rendering like Blender's BLF, Slug on the GPU, BUI_FONT, limits (no fallback, no IME, bidi without shaping). Sources: CHANGELOG.md, README.md |
theming.mdx |
70 | Blender's theme in BUI: where colors come from (userdef_default_theme.c), icons, what you can change today. Verify in kit/ before writing; mark anything unbuilt with <ComingSoon>. |
Performance (src/content/docs/performance/)
| File | Order | Scope |
|---|---|---|
benchmarks.mdx |
10 | The published results with their context: start time and battery, frame times, Rust vs gpui, JavaScript startup and animation. Source: README.md#performance |
run-benchmarks.mdx |
20 | How to rerun every benchmark, one at a time. Sources: README.md#run-the-benchmarks-yourself, bindings/rust/bench/README.md |
profiling.mdx |
30 | BUI_PROFILE=1, choosing a renderer, keeping lists on signals, common slow paths. Sources: README.md, docs/javascript.md#performance |
Reference (src/content/docs/reference/)
| File | Order | Scope |
|---|---|---|
environment-variables.mdx |
10 | Every BUI_* variable, what it does, defaults. Source: docs/getting-started.md#environment-variables |
cmake-options.mdx |
20 | Every CMake option with default and effect. Sources: docs/getting-started.md#build-options, CMakeLists.txt |
platforms.mdx |
30 | The full platform matrix and per-platform notes. Source: README.md#platforms |
coverage.mdx |
40 | Coverage numbers in one place: tkinter, Qt, HTML, CSS, Tailwind, ImGui. Sources: SYNTAX_COVERAGE.md, docs/rust.md#coverage, docs/qt.md#coverage |
glossary.mdx |
50 | Kit, binding, node, host, render sink, damage rendering, raster, Slug, signal, styled … one or two sentences each. |
Project (src/content/docs/project/)
| File | Order | Scope |
|---|---|---|
faq.mdx |
20 | The README FAQ, expanded: Blender not needed, unchanged tkinter, not a browser, real ImGui, vs Electron, macro cost, why GPL. Source: README.md#faq |
contributing.mdx |
30 | How to help: issues, PRs, tests, the code of conduct, security reports, writing docs (link this guide). Sources: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md |
publishing.mdx |
40 | Releasing to PyPI, npm and crates.io (for maintainers). Source: docs/publishing.md |
changelog.mdx |
50 | A readable summary of CHANGELOG.md with a link to the full file; don't copy it wholesale. |
license-and-credits.mdx |
60 | GPL-3.0-or-later (like Blender) and why, per-file headers, third-party licenses, acknowledgments. Source: README.md#license |
9. Before you open a PR
- Frontmatter complete:
title,description,section,order,sources. - A hook in the first lines and next-step cards. No
<Recap>, no emoji. - Per-language page: no comparisons with other languages.
- Rust page: every UI example in both
rsx!and gpui builders. - Demo tricks mentioned at most once; typed math only for number fields.
- A
<Figure>(or anIMAGE:placeholder) wherever a UI result is shown. - Every number and name checked against the repository.
- Unbuilt features marked with
<ComingSoon>(andstatusif the whole page is). - Code examples are complete and runnable as shown.
- At most one joke.
-
pnpm buildpasses with no warnings; the page looks right in light and dark, on a phone and a desktop.