Ace3 Documentation

VitePress documentation for Ace3, the World of Warcraft addon framework: AceAddon, AceDB, AceConfig, AceGUI-3.0 and the rest of the suite.

The reference is generated by hand but verified against the Ace3 Lua source, which is vendored as a git submodule ( Ace3/, from WoWUIDev/Ace3).

Getting started

git clone --recurse-submodules https://github.com/nickdnk/wowace-docs.git
cd wowace-docs
pnpm install --ignore-scripts
pnpm docs:dev          # local dev server with hot reload

Already cloned without submodules? Pull the source:

git submodule update --init

Scripts

Command	Description
pnpm docs:dev	Start the dev server.
pnpm docs:build	Build the static site to .vitepress/dist.
pnpm docs:preview	Preview the built site locally.

Structure

• getting-started.md (guide) · index.md (home)
• api/*.md: one page per library (+ ace-config-options, callback-handler)
• acegui/: AceGUI overview/tutorial, widget-api.md, widgets/*, containers/*
• .vitepress/config.ts: site config + the apimethod authoring macro
• .vitepress/theme/: ApiMethod.vue, custom.css
• Ace3/: submodule, the authoritative Lua source (do not edit)

Contributing

Everything is verified against the Ace3/ source; it is the single source of truth.

Authoring API entries

API methods are written as fenced apimethod blocks (four backticks). A markdown-it macro in .vitepress/config.ts expands each block at build time into a ### Name heading (which feeds the page outline, search and anchors, and is then visually hidden) followed by an <ApiMethod> card.

````apimethod
name: AceDB:New                  # full Object:Fn; the heading shows just the bare method name
kind: method                     # optional: "method" (default) or "callback"
params:
  - { name = "tbl", type = "string|table", desc = "SavedVariables name, or a table to use." }
  - { name = "defaults", type = "table", default = "nil", desc = "Table of database defaults." }
  - { name = "defaultProfile", type = "string|boolean", optional = true, desc = "Starting profile name." }
returns:
  - { type = "table", desc = "The new database object." }
---
Markdown description of what the method does.
---
```lua
-- optional example; renders last (after the tables) under an "Example" heading
self.db = LibStub("AceDB-3.0"):New("MyAddonDB", defaults)
```
````

Rules:

• params and returns are Lua table literals, one per - { ... } line. Params use fields name, type, desc, and optionally optional / default:

  • mandatory: neither optional nor default (the caller must pass it).
  • optional = true: may be omitted; no documented default value (omitting it just leaves it unset/nil).
  • default = "…": the value the param takes when omitted or passed as nil. A default implies optional.

  There is no required field; a param is mandatory simply by having neither optional nor default.

• returns uses the same Lua-table format: one - { type = "…", desc = "…" } per returned value (add a name for a multi-value return). It renders as a Type | Description table. A single value may also be written inline as one object: returns: { type = "<type>", desc = "<description>" }.

• The signature is generated from name + params in declared order; you never write it. Optional params get a ? suffix; a varargs param named ... is shown as-is (e.g. Printf(chatframe?, format, ...)); a union argument is expressed by naming the param accordingly (e.g. prototype|lib).

• Optional fields: title: overrides the heading text; kind: callback switches the badge and is used for callbacks/events.

• The body has up to two ----separated parts. The first --- separates the header (above) from the markdown description. An optional second --- marks an example: the lua block after it is pulled out and rendered last, after the parameter/return tables, under an Example heading. Methods that need no example just omit the second ---. Don't add an example that only restates the signature.

A block renders to a Lua-highlighted signature, a method/callback badge, a Parameter | Type | Default | Description table, a Type | Description returns table, and (when a second --- is present) the example under an Example heading.

Conventions

• Backtick all code in prose; use lua fenced blocks for Lua.
• Link method references to their anchor; link other Ace libraries to their page; link Blizzard/Lua/event/frame APIs to warcraft.wiki.gg (Ace3's own API stays on-site).
• Tutorials explain purpose with examples and link to the API reference rather than restating signatures.
• Examples show one canonical approach, not stacked alternatives.

Updating the Ace3 source

The submodule pins a specific Ace3 commit. To document a newer version, update it deliberately:

git -C Ace3 pull origin main
git add Ace3 && git commit -m "Bump Ace3 source"