Repository navigation
Releases
Releases · kohltastrophe/luaudocs
v0.3.2
Changed
- Release parsed CSTs after extraction. (07d2889)
Fixed
- Avoid false-positive member realms on project tables. (976106e)
- Fold literal binary expressions during surface evaluation. (6a67952)
- Preserve tags on respelled type aliases. (bcff882)
- Handle nested generic alias references in rendered pages. (028147b)
- Unshallow shallow Git clones before VitePress build. (433fb0b)
Full Changelog: v0.3.1...v0.3.2
v0.3.1
Changed
- Generated
llms.txtheaders and.github/workflows/docs.ymlnow runnpx luaudocs@latestand keyactions/cacheon the latest npm release version. luaudocs llmsnow skips fetching external dependency doc models because localllms.txtoutput links signatures to localfile:linedeclarations.
Fixed
- Fixed false-positive
Yieldsbadges on*AsyncandYield*helper functions that don't actually yield. - Fixed cross-module call resolution inside
RunService:IsServer()andRunService:IsClient()guards. - Fixed
::type cast unwrapping onsetmetatable(M :: any, MT)andtable.freeze(M :: any). - Fixed
MT.__index = Prototable delegation and kept modules with unreturned@class-tagged local tables in the documented graph. - Fixed
@ignorehandling on@within-relocated fields, unreturned local classes, and standalone@prop,@function, or@fieldtag blocks. - Fixed composite generic types with suffixes (
Sub.Foo<T>?), generic parameter copying on re-exported type aliases, and type linking insidetype functionparameter lists. - Fixed
selfinsertion on re-exported methods that have->function types in generic defaults. - Fixed cross-site dependency linking through passthrough entry modules (
return require(...)), re-export badge links on runtime-alias mounts, and dotted module mount paths (M.Sub.Leaf = require(...)). - Fixed heading anchor prediction after
<Frame>or<Tabs>blocks,base-prefixed badge links inside<Frame>headings, YAML frontmatter quote escaping, and disambiguated page titles in/llms.txt. - Fixed CLI path validation for missing or non-directory project paths, and stabilized the
luaudocs devwatcher when<docs>,README.md, orCHANGELOG.mdsits inside[source] entries.
v0.3.0
Added
- Classes defined separately from their constructor table are documented.
Typed Luau libraries often keep methods on a local self-indexing table that
the module never returns (local Deque = {},Deque.__index = Deque,
function Deque.pushback(self: Deque<T>, value: T)) and return a table
containing onlynew, which attachesDequeviasetmetatable(_, Deque).
The extractor now follows that attachment (or a type that declares it via
typeof(setmetatable(_, Deque))orsetmetatable<_, typeof(Deque)>; bare
setmetatable<D, M>is not recognized as a class type) and documents the
table as a class named after the type (or the local variable when no type
names it), with the constructor grouped under the class.
Self-indexing (T.__index = T) alone still does not make a table a class:
thesetmetatableattachment is what distinguishes a class from a
self-indexing module namespace. - Requires of runtime modules are treated as external rather than unresolved.
Requiring a module through a runtime-supplied alias (@lute/fs,@std/path,
@lune/net) rather than.luaurcno longer emitsrequire-unresolvedon
every build. Lute and Lune aliases are built in, and[source.aliases]lets
you register custom runtime aliases or override built-in ones with a
documentation base URL. Mounting a runtime module renders as a property
showing therequire(...)call and linking to its documentation URL, and
types referenced through a runtime alias (fs.File) link to that module's
page just like Roblox types link to Creator Documentation. A.luaurcalias
of the same name still takes precedence. In the doc model,Reexportgained
an optionalurlfield for runtime mounts, andexternalsvalues are now
either the URL string declared by@externalor an object
{ url?, alias, path, name? }for types reached through a runtime alias. - Sites can cross-link to each other's symbols. Setting
[docs] model = true
publishes the doc model atpublic/docmodel.json, and configuring a
[source.aliases]entry as{ url, model }loads that external doc model so
types reached through the alias link directly to their exact#anchoron the
external site rather than only to the module page.modelaccepts either an
http(s)://URL (fetched and cached per user, with the cache used as a
fallback when offline) or a project-relative file path; an unreadable model
emits a warning and falls back to module-level links. Existing sites should
add/public/docmodel.jsonto their docs directory's.gitignore(newly
scaffolded sites include it automatically). [api] reportUndocumentedgates documentation coverage. When enabled, it
emits anundocumentedwarning for every public member, class, and exported
type without a doc comment, formatted as callers write it (Widget:refresh),
soluaudocs build --strictfails until the public surface is fully
documented. Disabled by default.- Exported types in tags-only modules are reported instead of silently dropped.
When a module is required only for its types (for example,local types = require("./types"))
and never mounted on the public surface, its unreached exported types now emit
anunreached-typesinfo diagnostic naming the types and the two ways to
surface them (export type Name = ...in a public module or@withinon the
declaration). Types already re-exported by a surfaced module
(export type Hook = types.Hook) are excluded. function T.f(self: T, ...)documents as a method. Explicitly typing
selfas the first parameter of a dot-defined function (which Luau's:
syntax cannot annotate) now renders with:syntax (T:f(...)) and omits
selffrom the parameter list, and a single such method is enough to classify
Tas a class. Adding@functionstill forces it to render as a dot
function withselfkept in the signature.- Lazy module loaders,
typeof(require(...))mounts, and__indexdelegation.
Functions whose body isreturn require(X)followXin the module graph and
inferXas their linked return type when unannotated or annotated
typeof(require(X)). Table fields declared asKey: typeof(require(...))on
a returned table's type annotation synthesize module mounts, and
setmetatable(M, { __index = Proto })delegates fields fromProto(including
whenProtocomes from a local factory call). - Container type annotation fallback and expanded re-exported types.
Unannotated properties (or properties cast to:: any) fall back to the field's
type and doc comment on the owning table's type annotation, and re-exported
type aliases (export type T = Other.Torexport type T<U> = Other.T<U>)
expand the origin type's underlying definition, generics, fields, and fallback
doc comment. luaudocs llmsgenerates a project-rootllms.txtfor coding agents.
While the site's/llms.txtserves AI tools browsing your deployed docs,
luaudocs llmswrites a compactllms.txtat the repository root for coding
agents working in a local checkout (referenced fromAGENTS.mdor
CLAUDE.md). It indexes your guide files followed by one section per module,
headed by therequire(...)expression that reaches the module and listing
its types and members as Luau signatures linked to theirfile:line
declarations. It requires noluaudocs initor VitePress build and reads only
committed repository files; its header instructs agents to rerun
npx luaudocs@<version> llmsafter changing the public API, doc comments, or
guides. Pass--checkin CI to fail on a missing or stalellms.txt, or
--out <file>to write to another path. LuauDocs refuses to overwrite an
llms.txtthat does not carry its generated marker, and aborts without
writing when extraction produces an error. See
Coding Agents.- Cloudflare Pages deployment guide.
Deploying now
documents building and hosting directly on Cloudflare Pages without a GitHub
Actions workflow file.
Changed
- Documentation site moved to
luaudocs.pages.dev.luaudocs.kohl.gg
redirects to the new domain, and package metadata plus newly scaffolded
starter guides now link toluaudocs.pages.dev. - Stricter configuration validation for paths and URLs. Setting
[docs] dir
at or outside the project root (".","..","../site", or/abs/path)
is now rejected so a build can never overwrite the project's own
package.jsonorCHANGELOG.md. URL fields and--urlmust usehttp://
orhttps://, preventing host-only strings (docs.example.com:8080) from
being parsed as URL schemes and preventingssh://repo URLs from generating
unclickable source links.[docs] diris also normalized to clean POSIX
form so./docs/no longer leaks leading./or trailing slashes into edit
links and the GitHub Pages workflow. initvalidates existingluaudocs.tomlfiles and probes conventional source roots.
luaudocs initnow fails fast on an invalidluaudocs.tomlinstead of
falling back to default settings, and scaffolds[source] entriesfrom the
existing conventional directories (src/,lib/) so projects usinglib/
build out of the box.- The scaffolded GitHub Pages workflow caches
~/.cache/luaudocsalongside
npm andnode_modulesso CI runs reuse the downloaded Lute binary. - VitePress build failures exit with code
1(build failure) rather than
2(usage/config error). - Constructor detection requires a bare class return type (with optional
generic arguments): functions returningWidget?,{ Widget }, or
Promise<Widget>are no longer classified as constructors ofWidget. - Root functions that re-expose an implicit class's constructor or method
(return { new = Signal.new }) are documented once on the class rather than
duplicated on the module root. - Internal contracts updated in place:
Reexportin the doc model gained
optionalrealmandwithinfields; the generated API sidebar navigation
moved to.vitepress/generated/api-nav.ts; and generatedchangelog.md
files now include the# Generated by luaudocsownership marker.
Fixed
- Conditional module mounts written
M.Server = RunService:IsServer() and require(...)
now document the mounted module and attach its realm badge instead of
rendering as an untyped property. - Re-exports inside nested containers now render on the nested class section
rather than the module root, and member imports targeting an undocumented
symbol fall back to rendering as a property alongside the
unresolved-reexportdiagnostic. - Modules promoted to a page solely by a
@classtag now also surface the
submodules they mount. - Block doc comments with text on the opening delimiter line (
--[=[ Summary.)
now dedent their body lines properly instead of treating indented@param
tags as indented code blocks. @returntype overrides now update the rendered function signature just like
@paramtypes, and merging a standalone@functiontag stub into a source
function preserves the stub's@returnentries and warns on unmatched
@paramor@returntags.@propand@readonlytags on a table-valued field keep it documented as a
property rather than promoting it to a nested class, and@class,
@function,@prop, or@methodblocks placed directly above atype
declaration are no longer consumed as the type alias's doc comment.unreached-typesno longer reports types that were moved to a surfaced class
via@within, and unexported local type aliases are omitted when an
@within-relocated exported type already owns that name on the page.- Duplicate member declarations that resolve t...
v0.2.0
Added
_category_sidebar sidecars for guide folders. A_category_.json
(or_category_.yml) beside a folder's pages names, places, and collapses
the group it becomes, reading thelabel,position,collapsed, and
collapsiblethat Docusaurus and Moonwave already wrote there. Setting
collapsibletofalsedrops the toggle for a group that is always open.
A folder with anindex.mdcan putsidebar_position,collapsed, and
collapsiblein that page's frontmatter instead, and the sidecar outranks
it key by key. A position is any number Docusaurus accepts, so a migrated
2.5still slots between 2 and 3. A sidecar that does not parse fails the
build, named.init --from-moonwavenow copies these files across instead
of reporting them as unportable, naming only the keys the sidebar does not
read (link,className); one that does not parse aborts the conversion
before anything is written, as a malformedmoonwave.tomldoes.- Underscore-prefixed guide folders and pages are left out, as Docusaurus
leaves them out: not in the sidebar, not built, not in search orllms.txt.
A_drafts/folder or a_partial.mdfor<!--@include: -->no longer
lists itself.
Changed
devreloadsluaudocs.tomlin place instead of exiting and asking to
be restarted. The config is re-read, the watchers rebind to whatever
[source] entriesnow names, and the rebuilt site config is what the
VitePress server restarts itself on. A config that does not parse keeps the
session running on the last one that did, so a half-typed edit costs an
error line rather than the server, and so does aluaudocs.tomlthat a
stash or a branch switch takes away. Moving[docs] dirstill ends the
session, since the server is bound to the directory it started on.sidebar_positionis read against a page's siblings alone, so the pages
in a subdirectory number from 1 rather than continuing the count outside it.
A group used to take the lowest position among its children, which meant
placing a folder required numbering its pages in the parent's sequence; a
group is now placed by its own_category_file orindex.md, and one that
declares no position sorts last. A site that relied on the old behavior
should give each folder a_category_.jsoncarrying the position its pages
used to imply.- An
index.mdleads the folder it sits in, ahead of any position a
sibling declares, and at the top ofguide/too: aguide/index.mdnow
opens the Guide sidebar whateversidebar_positionit carries, where it
used to sort by that position like any other page. An index page's position
places its folder among the folder's siblings, so on the top-level one it
places nothing. - A guide folder heads its own sidebar section when nothing sits loose.
Whenguide/holds only folders, the single "Guide" heading over them is
dropped and each folder becomes a top-level section, so a site organized
entirely into folders no longer reads as one group of groups. A section
head has no toggle unless its_category_file orindex.mdsets
collapsedorcollapsible. Aguide/with any page directly inside it
keeps the "Guide" heading it had. - The nested sidebar groups above the current page take the brand color,
the same as the entry for the page itself. VitePress only lifted them from
the muted text color to the plain one, which left the open group looking
like every other. Section heads keep the plain color, and light only when
they link to the current page.
Fixed
- A frontmatter key left blank (
title:on a line of its own) no longer
reads the line below it as its value.
v0.1.0
First public release.
Added
- Surface discovery without tags. The extractor symbolically evaluates a
module's top-level statements down to its return value, so functions,
methods, properties, nested classes, re-exports, andexport types are
documented from the code itself. Table literals,__indexclass idioms,
setmetatableandtable.freezewrappers, cast types, member imports, and
conditional mounts are all recognized. A leading underscore keeps a member
out of the site, with@private,@ignore, and[api] includePrivateas
the overrides. - Badges detected from code. A function that waits (
task.wait,
signal:Wait(), a yielding engine method, apcallrunning one, or a call
to something that does, followed across modules, imports, passthroughs, and
__callmetatables) is badged Yields without a tag. Remote calls,
realm-only services, Studio-only members, and thepluginglobal badge a
function Server, Client, or Plugin, and a prop renders Read Only when its
table istable.freezed or its field is markedreadin the table's type.
The tags stay as overrides: a realm tag replaces whatever was detected. - Parameter docs from trailing comments. In a multi-line signature, the
trailing-- commenton a parameter's line documents that parameter, the
way it already documents a property or a type field;@paramoutranks it. - Signatures from real type annotations, spelled the way you wrote them.
Every type mention links to its definition, and Roblox types link to the
creator docs. - Property types read off the value. A property nothing annotates still
documents its type when the value settles it: literals and comparisons,
Color3.new(...)and other datatype constructors,Enum.X.Y, an instance
path, an engine method called on a service, a list of literals, and a call
into your own code, which takes the callee's annotated return and links to
it (across modules, so a library of.newconstructors needs no tags). A
value that settles nothing (a + b,script.Name) stays untyped rather
than guessing, and an annotation, a cast, or a floating@propalways wins
over what was inferred. - Aliases link to what they alias. One table reached by two names in a
module gets one documented section, and the other name is typed as a link to
it rather than rendering bare beside it. The cross-module case is still a
re-export, which names the hop it crossed. - Conditional mounts badge their realm. A property written
RunService:IsServer() and script:WaitForChild("Storage")is badged Server
and typedInstance?from that one expression: the guard says where the
value exists, the guarded half says what it is. A value guarded by an
already-guarded one carries the same realm. A guard over a plain boolean is
a predicate rather than a mount, so it keeps itsbooleantype and no
badge, since the other realm can read it and find it false. - References that link themselves. A
[State:Connect]in a doc comment
becomes a link, resolved against your project,@externaldeclarations, and
Roblox names; one that resolves to nothing stays plain text. When one
spelling could mean two things, a module outranks a
same-named type and a re-spelling alias cedes to the declaration it
re-spells; only a genuine tie is left unlinked, reported with both targets. - No toolchain to install. Node is the only requirement. The extractor runs
on a pinned Lute that the first extraction downloads, verifies against a
checksum, and caches per user.LUAUDOCS_LUTEpoints LuauDocs at a Lute
build of your own, for an offline machine or a platform with no prebuilt
binary. - Moonwave compatibility. All 24 Moonwave tags keep working as overrides,
so tagged sources need no edits.luaudocs init --from-moonwaveconverts
the config (moonwave.tomlormoonwave.json, navbar and footer included),
copies.moonwave/static/, and ports the hand-written pages:docs/lands
underguide/and the markdown underpages/at the site root, with.mdx
renamed, MDX imports and comments stripped, and links, static-asset paths,
and fence titles respelled, while draft and unlisted pages stay unpublished.
The homepage banner and feature cards become anindex.mdin VitePress's
home layout, and.moonwave/custom.cssarrives with the known Infima
variables renamed. Whatever has no equivalent is named in a report rather
than guessed at. Docusaurus markup converts at render time, in doc comments
and guide pages alike::::noteand:::cautionbecome VitePress
containers (bracket titles unwrapped), and<Tabs>/<TabItem>groups
become VitePress's own tab strip. - A generated VitePress 2 site, wired up from
luaudocs.toml: local
search, dark mode, Luau highlighting in both fences and inline
`code`{luau}spans, tool and file-type icons on code-group tabs and
fence titles,[[site.head]]for analytics and verification tags,
sitemap.xmlfrom[docs] url, andllms.txtplusllms-full.txtat the
site root.<docs>/api/and<docs>/.vitepress/are wholly tool-owned and
rebuilt by every build; your content sits beside them and is scaffolded only
once. - Fira Code for code, in fences and
inline spans both, with its programming ligatures on. The font ships with the
tool and is served from your own site (no request to a font CDN, and no
network indev), as one variable file covering every weight. Set
--vp-font-family-monoincustom.cssto use something else. - Your README and CHANGELOG become pages. While the docs directory has no
index.md, every build makes the landing page from yourREADME.md, marked
as generated until you claim the file, andCHANGELOG.mdrenders at
/changelog. - Source links from
[repo] url, whichinitfills in from your git
remote: every entry links to the lines that produced it, and the site gets
edit links and the header's GitHub icon. - Navigation that mirrors usage. The sidebar is the access-path tree
derived from the code: pages group by how a caller reaches a module rather
than by folder layout, falling back to the Rojo instance tree (or the folder
layout) for modules that nothing exposes. There are no keys to reorder, pin,
or rename groups. Two modules sharing a name stay distinguishable: the later
gets a numbered URL and carries its parent in the sidebar, search, and tab
title (Defaults (Flux)). Every page also heads with a trail of links to
what is above it (Home › Overview › Flux › Utilon an API page,Homeand
the enclosing folders on a guide), so a reader arriving from search or a deep
link sees where the page sits. It renders above the title, which is where
VitePress's search indexer stops reading, so navigation never enters the
index. - Type entries. Every exported type, and any local type a documented
signature mentions, becomes a documented entry with per-field descriptions,
taken from doc comments above fields or trailing comments on them. Atype functiondocuments as its callable head with parameters, the body behind
the source link. A tag-written type name resolves against the modules the
file actually binds, never an unrelated module's same-named class. - Require resolution across string requires,
.luaurcaliases, Roblox
instance paths, Rojo*.project.jsonmounts, and nested projects. - CLI:
init,dev(watch plus HMR), andbuild(--emit-only,
--strict,--url,--model);luaudocs build --emit-only --strictis the
CI validation.initalso scaffolds the GitHub Pages workflow at
.github/workflows/docs.ymlwhen the file does not exist. - Extraction never fails silently. Anything LuauDocs could not do becomes
a diagnostic with a location, severity, and code, and--strictpromotes
warnings to failures. An error build refreshes the pages that did emit and
withholds every destructive step, so a transient typo cannot look like an
intentional removal. <Frame>, a labeled border for quoting generated output in a guide.
Paired with a VitePress file inclusion, it embeds an entry from your own
api/pages by stable region name, and a name that stops existing fails the
build instead of quietly emptying the frame. See
Reference: Markup.- The doc model as an output.
luaudocs build --model <file>writes the
JSON the renderer consumed: every module, member, type, and signature, with
type references resolved to the ids of the declarations they name, and
diagnostics alongside.schemaVersionis1, and the shape changes in place
while the major version is0. See the
doc model reference. - Guide-only mode (
[source] entries = []) for projects with no Luau
surface: the extractor never runs and no Lute is fetched.