---ldoc config
---@diagnostic disable: lowercase-global
-- luacheck: ignore 111
project = "texrocks"
title = "TeXRocks, a minimal (La)TeX distribution"
format = "markdown"
pretty = 'lxsh'
dir = "_readthedocs/html"
template = "assets/html"
readme = {
  "README.md",
  "docs",
  "_readthedocs/markdown",
  -- for build.lua
  [0] = [[
TeXRocks is a minimal (La)TeX distribution powered by Luarocks/Lux and LuaTeX.

It has the following features:

- virtual environment: all TeX packages are installed to
`.lux/5.3/XXXXX-package_name@version/`, like nodejs's `node_modules/` and
python's `.venv/`. After development of PDF, You can delete it safely, and it
will not affect your next development of PDF.
- minimal: we only install required packages
- package version control: when you declare `latex-base == "2025.06.01-1"`, it
will install <https://luarocks.org/modules/freed-wu/latex-base/2025.06.01-1> not
other versions! pin the version like nodejs's `package.json` and python's
`requirements.txt`
- package installation in parallel: install many packages at the same time
- a server to host compiled TeX packages: <https://ustctug.github.io/texrocks/>
- use lua to develop TeX packages: <https://luarocks.org/m/texmf>

We also provide some related TeX tools, like kpsewhich and texdef written in
lua. See official website <https://texrocks.readthedocs.io/>
]]
}
file = {
  "lua",
  "_readthedocs/lua",
}
description = title
full_description = readme[0] .. [[
## Quick Start

First coming?

- [tutorial](topics/README.md.html): the steps to build a TeX project
- [install and configure](topics/install.md.html): read it before all examples
- [draw a graph](topics/demo-tikz.md.html): an example for LaTeX
- [use bibliography](topics/demo-bib.md.html): another example for LaTeX
- [write markdown](topics/demo-markdown.md.html): try markdown!
- [write a thesis for ieeetran](topics/demo-ieeetran.md.html): a complex project.

## TeX Dialects

Which TeX do you want to use?

- [plainTeX](topics/luatex.md.html): first TeX
- [LaTeX](topics/lualatex.md.html): most people needed TeX
- [TeXinfo](topics/luatexinfo.md.html): GNU's TeX
- [sdLuaTeX](topics/sdluatex.md.html): [speedata](https://www.speedata.de/)'s TeX
- [A toy TeX](topics/initex.md.html): how to create a new TeX dialect?

TODO:

- ConTeXt

## TeX Tools

Some useful tools for development!

### Developed by others

- l3build: a tool to test/build/pack TeX packages developed by LaTeX 3 team
- light-latex-make: read XXX.log to decide if rerun TeX compiler.
- texdoc: a tool to search document of any TeX package developed by TeX Live
  team. It needs an extra [configuration](topics/texdoc.md.html).
- luafindfont: a simple tool to search fonts

### Developed by ours

- [texdef](topics/texdef.md.html): which TeX package defines `\macro`?
- [epstopdf](topics/epstopdf.md.html): call ghostscript to convert eps to pdf
- [texcat](https://tree-sitter-highlight.readthedocs.io/en/latest/resources/texcat.html):
  a new syntax highlight system to replace [minted](https://github.com/gpoore/minted)
  based on python's [pygments](https://pygments.org/)
- [luarocks-build-l3build](topics/luarocks-build-l3build.md.html): Luarocks
  build backend for packing TeX packages. More TeX packages are needed:
  CTAN ~3000 v.s. <https://ustctug.github.io/texrocks/> ~100. Welcome to pack!

## Learn More

Know what is under the hood.

- [Structure](topics/structure.md.html): What does it consist of?
- [Principle](topics/principle.md.html): How does it work?
- [Roadmap](topics/roadmap.md.html): which features TeXRocks have supported and
  will support?

## Others

- [manifest](https://luarocks.org/m/texmf): list all current TeX packages
- [rocks](https://ustctug.github.io/texrocks/): some packages cost many time to build. We provide compiled packages for them!
- [repository](https://github.com/ustctug/texrocks): git repository, also include this website.
- [CTAN](https://ctan.org/pkg/texrocks): CTAN homepage

## Related Projects

- [mmTeX](https://github.com/vlasakm/mmtex): the earliest plainTeX distribution.
- [aplTeX](https://github.com/RadioNoiseE/apltex): inspiration source
- [TinyTeX](https://yihui.org/tinytex): a small customized TeX Live fork.
- [TeX Live](https://tug.org/texlive): official (La)TeX distribution
- [MikTeX](https://miktex.org): another famous (La)TeX distribution
]]