Lua-Modules

Lua Modules are an integral part of Liquipedia. They allow for more complex logic for rendering elements. Any modules added in this repository will, after a review process, be added to the modules and templates of the website.

Note: Modules in this repository are only a subset of those on the website. Any 'duplicates' on the website will be overwritten by those in this repository.

Contributing

If you want to contribute you may do that in any way you wish. We use the following steps for onboarding new developers.

Setup

Dependencies Installation

Clone the repository. This requires git to be installed on your system.

Windows

Recommended to use WSL. Then follow the Unix instructions.

Unix (Linux Ubuntu)

Installing Lua and Luarocks

1. Follow these instruction on installing needed development tools on your system.
2. Instead of downloading and unpacking the latest Lua version, download lua-5.1.tar.gz from lua.org and unpack it.
3. Follow the instructions linked above for the rest of the process.
4. If you have done everything correctly, you should now have Lua and Luarocks installed on your system.

Installing busted and luacheck

1. Run luarocks install --lua-version=5.1 busted to install busted (used as a testing framework).
2. Run luarocks install --lua-version=5.1 luacheck to install luacheck (used for linting).
3. Make sure installed rocks are available in your path variable.
4. Test if everything is correctly installed by running busted -C lua and luacheck lua --config lua/.luacheckrc from the root of this project. If all tests pass and all checks are OK, you're installation of busted and luacheck is complete.

Installing npm, node and dependencies

1. Follow the instructions here to install npm
2. Run nvm install node
3. Run npm install

Mac

• Install Lua. We use version 5.1. There are some 5.2 features which are available, but nothing from 5.3 onwards. Using a newer version is not recommended or supported. The lua version is restricted as we use LuaJit. If you're curious. Using brew will warn you that lua 5.1 has been deprecated and installing is disabled. Can be installed by editing the file with brew edit lua@5.1. Remove the line that says disable! date: "2022-07-31", because: :unmaintained Finally run HOMEBREW_NO_INSTALL_FROM_API=1 brew install lua@5.1 which will then install it anyway.
• Install the package manager, LuaRocks brew install luarocks
• The project contains two third party dependencies, busted and luacheck. Install both through luarocks
  • luarocks install --lua-version=5.1 busted <- used as a testing framework
  • luarocks install --lua-version=5.1 luacheck <- for linting
  • Make sure the installed rocks are available in your Path variable. How to do this might depend on your choice of terminal.
  • Test if everything works by running busted from the command line in your projects root folder. If the tests run and are all green you should be good to go.
• Install an ide/texteditor of choice. The repo contains some presets for Visual Studio Code.

IDE

Visual Studio Code

We recommend VSCode. Highly recommend that you get the extension Lua. The repo is setup with presets for this.

Eslint and Stylelint extensions are recommended if you're going to work with stylesheets or javascript.

Intellij

Highly recommend that you get the extension SumnekoLua.

Eslint and Stylelint extensions are recommended if you're going to work with stylesheets or javascript.

Neovim

1. Add lua_ls in your Neovims lsp configuration (useful tools for lua files). Installation instruction can be found here.
2. Add eslint in your Neovims lsp configration (useful linting for Javascript files)
3. Add stylelint_lsp in your Neovims lsp configuration (useful linting for scss files). Make sure to add scss as a filetype to get the benefits of this LSP on scss files in this project. You can also enable autoFixOnSave or other settings if you want:

require('lspconfig').stylelint_lsp.setup {
  filetypes = {
    'css',
    'postcss',
    'less',
    'scss'
  },
  settings = {
    stylelintplus = {
      autoFixOnSave = true,
      validateOnType = true,
    },
  },
}

Adding a module

Modules start with a header like:

---
-- @Liquipedia
-- page=Module:$NameOfModule
--
-- Please see https://github.com/Liquipedia/Lua-Modules to contribute

The header is important, it is used by our automation to place a module in the correct location on the wikis. The page is like the path. It determines where within the wiki the file is deployed/hosted. Other files refer to each other based on this path.

Project

The project is divided into folders based on language. Even though the project is called Lua-Modules, a part of this repository is in different languages/techniques.

• In the javascript folder are scripts that run in the client. Our current setup does not fully support all available features in html. So for example a dropdown (select) element can't be rendered from our back end properly. We use javascript to add these kind of features. Essentially anything that makes an element interactable, buttons mostly, are constructed or configured from javascript.
• The modules written in lua are found in the lua folder.
  • Some modules are covered by unit tests. Tests are placed in the spec sub-folder.
• Styling is found in the stylesheets folder. For styling we use scss. Check out their documentation for getting up to speed on how this differs from traditional css.

Automated Testing

Javascript & Stylesheets

Run npm run test in the root folder.

You can run npm run fix for auto correctable issues to be fixed.

Lua

Run npm run lua-test in the root folder.

Visual Snapshot Testing

This project uses visual snapshot testing to verify UI components. Snapshots are automatically generated and updated by our CI pipeline to ensure consistency across platforms.

• You don't need to update snapshots locally
• Submit your PR, and our CI will automatically update snapshots if needed
• The updated snapshots will be committed back to your PR branch
• Review the snapshot changes as part of your PR review process

Committing changes

You need to be a member of the Liquipedia organization before you are allowed to push to this repository. In most workflows, you will make a fork of this repository to your own repository, and request a merge request from there. See the wiki for a step-by-step guide on how to commit a change. Trusted contributers may be given the privilege of directly branching within the repository. These privileges are always up to the discretion of Liquipedia staff.

Testing your branch

Deploying your branch to a dev environment publishes your modules to sandbox pages (suffixed with /dev/<name>) on the wiki, so you can render and test them without touching the live pages.

Via a GitHub Action

To test your changes in action, you can run the GitHub Action called "Personal Deploy" defined in .github/workflows/deploy test.yml. You can do it either through the GitHub interface or with the GitHub CLI tools: gh workflow run 'deploy test.yml' -r <BRANCH NAME> -f luadevenv=<DEV-ENV-NAME>

To check the workflow progress from the CLI, you can run: gh run list --workflow="deploy test.yml"

From your machine

You can also run the deploy script locally. This works from any editor — the repo ships a Visual Studio Code integration, and every other editor can call the same script directly.

One-time setup:

1. Install the Python dependencies: pip install -r requirements.txt
2. Copy .env.example to .env and fill in your bot account credentials. .env is git-ignored — never commit it.

WIKI_BASE_URL=https://liquipedia.net
WIKI_UA_EMAIL=you@example.com
WIKI_USER=YourBotAccount@BotName
WIKI_PASSWORD=YourBotPassword
DRY_RUN=0

Running it:

# Deploy specific files
python scripts/deploy.py lua/wikis/commons/SomeModule.lua [more files...]

# Deploy every file changed on your branch under lua/wikis/
python scripts/deploy.py

The behaviour is driven by environment variables (set them in .env or per-invocation):

Variable	Purpose
LUA_DEV_ENV_NAME	Sandbox suffix, e.g. /dev/myenv. Appended to every deployed page name. Set this for all dev testing — without it, deploys go to the live module pages. Also required to enable the no-argument "all changed files" mode.
LUA_DEV_BASE_REF	Ref that the no-argument mode diffs against to find changed files. Defaults to main.
DRY_RUN	Set to 1 to run the full flow without writing to the wiki.
WIKI_USER / WIKI_PASSWORD / WIKI_BASE_URL / WIKI_UA_EMAIL	Bot credentials and target wiki (see setup above).

Note: running python scripts/deploy.py with no arguments and no LUA_DEV_ENV_NAME triggers a full re-sync of every module to the live wiki — this is the automated weekly-resync path and is not what you want for testing a branch.

Visual Studio Code: the repo includes tasks in .vscode/tasks.json — run Tasks: Run Task and pick Deploy current file or Deploy all changed file. Both prompt for the dev environment name and the base ref.

Other editors: bind a command to python scripts/deploy.py with the environment above. For example, a Neovim mapping can shell out to python scripts/deploy.py <file> with LUA_DEV_ENV_NAME=/dev/<name> set on the job's environment.

Support

If you encounter any issues or have questions, feel free to open an issue on GitHub or reach out to the Liquipedia community for support.

Acknowledgements

We would like to thank all the contributors who have helped in developing and maintaining this repository. Your efforts are greatly appreciated.

License

Most of this repository follows the license of the textual content of Liquipedia, check out the license file for more information, unless otherwise stated in a README.md for a directory, or in the header of a file.