lua-std-doc

The Lua 5.5 standard library, documented by rustdoc.

This repository abuses rustdoc as a documentation generator for a language it has never heard of. A small Rust crate models Lua's world and a client-side script rewrites rustdoc's vocabulary on the fly. The result is a browsable, searchable, cross-linked reference for Lua 5.5, with rustdoc's search index, sidebar, and theming intact.

📖 Live: https://tkr-sh.github.io/lua-std-doc/

The extended library

Beyond the standard reference, the extended cargo feature documents lua/extended.lua: 34 functions other languages ship in their standard libraries (inspired by Rust), implemented, tested, and usable today:

require("extended")

("a,b,c"):split(",")            --> { "a", "b", "c" }
("  hi "):trim()                --> "hi"
table.map({1, 2, 3}, f)
table.fold(t, f, init)
math.clamp(x, 1, 10)
print(inspect({ nested = { ok = true } }))

lua/extended.min.lua is the same library on a single line (Lua's grammar is newline-free once -- comments are gone), and lua/test_extended.lua is the assertion suite covering both:

$ cd lua && lua5.4 test_extended.lua
$ cd lua && EXT=extended.min.lua lua5.4 test_extended.lua

How the trick works

Rust concept	Rendered as
pub struct string;	data type string
pub trait tostring	metatable tostring (metamethods as functions)
impl blocks	Method form vs Library functions sections
Repeatable<T> param	...values: T (Lua varargs)
option<T>	T | nil, with nil linked to its type page
<T: tostring>	a clickable metatable bound
modules	libraries (math, io, os, coroutine, ...)

The machinery lives in three files:

• custom.html: injected into every page via --html-in-header. Swaps rustdoc's vocabulary (pub fn → function, Trait → Metatable, ...), rewrites the marker generics above at the HTML level so type links survive, and ships a small Lua syntax highlighter that emits rustdoc's own token classes (kw, string, number, comment), so both themes color Lua code through their existing variables. It cooperates with rustdoc's line numbers setting in both orderings.
• lua.css: the theme, and the extension stylesheet (--extend-css): hides Rust-only sections (auto traits, blanket impls), styles the logo and the function-call highlight class.
• src/*.rs: the reference itself, one file per library, in an MDN-ish per-function format: summary, Parameters, Return value, Description, Examples (every function has one, with outputs matching Lua 5.5's round-trip float printing), See also.

Building

Docs require nightly (pinned by rust-toolchain.toml) for doc_auto_cfg, which renders the "Available on crate feature extended only" badges; everything else is stable Rust.

$ just docs        # or the cargo rustdoc line from the justfile
$ open target/doc/lua_std/index.html

Deploying

.github/workflows/deploy.yml tests the Lua library, builds the site on nightly, and publishes target/doc/ to GitHub Pages on every push to main. One-time setup: repository Settings → Pages → Source → GitHub Actions.

Credits

• Lua and the Lua logo are from Lua.org; logo © 1998 Lua.org, graphic design by Alexandre Nakonechnyj.
• Reference content follows the Lua 5.5 manual, rephrased and with original examples.
• Per-function page structure inspired by luadocs.com.