diff --git a/.env-files/Gemfile.github b/.env-files/Gemfile.github index 8eceee697..2cac0081a 100644 --- a/.env-files/Gemfile.github +++ b/.env-files/Gemfile.github @@ -1,3 +1,4 @@ source 'http://rubygems.org' gem 'github-pages', group: :jekyll_plugins -gem "jekyll-gitlab-metadata" # for cross compatibility \ No newline at end of file +gem "jekyll-gitlab-metadata" # for cross compatibility +gem 'wdm', '>= 0.1.0', platforms: [:mingw, :x64_mingw, :mswin] diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..318e3adf8 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# tools/wiki.sh must keep LF line endings, or bash cannot run it. +tools/wiki.sh text eol=lf +tools/wiki.bat text eol=crlf diff --git a/.github/README.md b/.github/README.md index 1e9b31e25..fde799031 100644 --- a/.github/README.md +++ b/.github/README.md @@ -1,7 +1,184 @@ # AzerothCore Wiki -Welcome to the AzerothCore Wiki! This repository provides comprehensive documentation for setting up, configuring, and customizing the AzerothCore WoW emulator. +Read in: [English :gb:](README.md) | [Español :es:](README_es.md) + +Welcome to the AzerothCore Wiki! This repository provides comprehensive documentation for setting up, configuring, and customizing the AzerothCore WoW emulator. The live site is at [azerothcore.org/wiki](https://www.azerothcore.org/wiki/home). If you want to contribute to the wiki please open a PR in the /docs/ directory. -Any problems? [Open a issue](https://github.com/azerothcore/wiki/issues/new). +Any problems? [Open an issue](https://github.com/azerothcore/wiki/issues/new). + +## Running it locally + +### With Docker + +1. Install [Docker](https://docs.docker.com/get-docker/). +2. Run `docker compose up github-wiki-theme` +3. Open `http://localhost:4000/home` + +### Without Docker + +Requires [Ruby](https://jekyllrb.com/docs/installation/) and Bundler (`gem install bundler`). + +> [!NOTE] +> These steps were tested on: +> +> - Windows 11 25H2 (OS Build 26200.9457) with Ruby 3.3.11 and Bundler 4.0.12 +> - Ubuntu 24.04.3 LTS (kernel 6.8.0-90-generic, x86_64, systemd 255) with Ruby 3.3.0 and Bundler 4.0.19 + +#### With the test script + +- Windows: double-click `wiki.bat` in the `tools` folder, or open a command prompt in `tools` and run `wiki build` +- Linux and macOS: in the `tools` folder run `./wiki.sh build` + +The script installs the gems if needed, stops any old server still running on port 4000, and serves the site. Then open `http://localhost:4000/wiki/home`. + +The first run can be slow, because Jekyll has to generate more than 500 pages (see [Build times](#build-times)). `--verbose` is enabled by default, so each page is printed as it is built and you can see that Jekyll has not hung. If you would rather not see the build progress, remove `--verbose` from the last line of the script. + +##### Options + +Add these words after the script name. They can be combined, in any order. In PowerShell write `.\wiki` instead of `wiki`. + +| Option | What it does | +| :------ | :----------- | +| `build` | Builds the English pages only, reusing the previous build. This is the fast, everyday mode, and what the script does when no option is given. | +| `all` | Also builds the Spanish and Chinese translations. That is about 1,500 pages, so it takes much longer. | +| `clean` | Throws away the previous build and the downloaded theme, and rebuilds everything. Use it if a page looks stale or wrong, or after changing the sidebar, a layout or `_config.yml`. | + +Without `clean`, the script reuses the previous build and only renders the pages that changed. For that it keeps the theme in the `.theme-cache` folder, which is not committed. + +Windows, from the `tools` folder: + +``` +wiki build +wiki build all +wiki clean +wiki clean all +``` + +Linux and macOS, from the `tools` folder: + +```bash +./wiki.sh build +./wiki.sh build all +./wiki.sh clean +./wiki.sh clean all +``` + +##### Build times + +When the build finishes, the script prints how long it took and which options were used. These are the times measured so far: + +| System | Command | Pages | Time | +| :----- | :------ | :---- | :--- | +| Windows 11 | `wiki clean` | about 560 (English only) | about 6 minutes | +| Windows 11 | `wiki clean all` | about 1,500 (English and 2 translations) | about 40 minutes | +| Ubuntu 24.04 | `./wiki.sh clean` | about 560 (English only) | about 8 minutes | +| Ubuntu 24.04 | `./wiki.sh clean all` | about 1,500 (English and 2 translations) | about 54 minutes | + +After the first build, saving a page only rebuilds that page, which takes about 10 seconds. + +The site is served on `127.0.0.1`, so only your own computer can open it. To let other devices on your network reach it, set `JEKYLL_HOST=0.0.0.0` before running the script: + +Windows: + +``` +set "JEKYLL_HOST=0.0.0.0" +wiki build +``` + +Linux and macOS: + +```bash +JEKYLL_HOST=0.0.0.0 ./wiki.sh build +``` + +Local previews do not create the redirects from old page addresses, because on Windows and macOS those would overwrite the real pages. + +#### Manually + +Copy `.env-files/Gemfile.github` to the root of the repository and name it `Gemfile`. Jekyll only loads the theme and the GitHub Pages plugins when the Gemfile is there. The copy is git-ignored. Then run: + +```bash +bundle install +bundle exec jekyll serve --baseurl /wiki +``` + +Then open `http://localhost:4000/wiki/home`. Jekyll watches the files and rebuilds on save, so just refresh the browser. + +The `--baseurl /wiki` part makes the sidebar links work: they point to `/wiki/...` like on the live site. + +## Tools + +The `tools` folder has the scripts used to preview and maintain the wiki. The Python scripts need Python 3 and are run from the wiki folder. + +| Script | What it does | +| :----- | :----------- | +| `wiki.bat`, `wiki.sh` | Builds and serves the wiki locally. See [With the test script](#with-the-test-script). | +| `update_table_lists.py` | Adds new table and DBC pages to the lists and indexes. | +| `update_gm_commands.py` | Updates the GM Commands page from a database. | +| `local_theme_cache.rb` | Loaded by the build scripts to keep the theme between builds. It is not run by hand. | + +A script that changes pages writes a log of what it changed to `tools/logs`, which is not committed. `--log file.log` writes it to another file. + +### Table and DBC lists + +Run it after adding a database table page or a DBC page: + +``` +python tools/update_table_lists.py --check +python tools/update_table_lists.py +``` + +`--check` only reports what is missing. Without it, the script: + +- adds new table pages to `database-auth`, `database-characters` or `database-world` and to the Database Index, under the right letter. The database is read from the back link at the top of the page. +- adds new DBC pages to the DBC Index. +- sets the bullet of each entry: a dot for a page with descriptions, a diamond for a page that only has column names and types. +- keeps the number of DBC files on the index pages correct. + +The languages and databases it works on are set at the top of the script. Another docs folder can be given as the first argument: `python tools/update_table_lists.py path/to/docs`. + +### GM Commands page + +The script reads the `command` table of a running AzerothCore database and updates `docs/gm-commands.md`: + +``` +python tools/update_gm_commands.py +python tools/update_gm_commands.py -y +python tools/update_gm_commands.py --check +python tools/update_gm_commands.py --host 10.0.0.5 --user root --password secret +``` + +Without options it asks for the connection, and Enter keeps a default (`acore` / `acore` on `127.0.0.1:3306`, databases `acore_world` and `acore_auth`). `-y` uses the defaults without asking. + +| Option | What it does | +| :----- | :----------- | +| `--check` | Only reports what would change. | +| `--host`, `--port`, `--user`, `--password`, `--world-db`, `--auth-db` | Connection settings. | +| `--no-rbac` | Does not read the RBAC tables. | +| `--replace-rbac` | Also replaces the RBAC column of commands that are already on the page. | +| `--remove-missing` | Deletes commands that are no longer in the database, instead of flagging them for review. | +| `--page` | Path to another `gm-commands.md`. | + +Security and Syntax come from the database. Descriptions that are already on the page are kept, and a new command gets the help text of the database as its description. It needs PyMySQL, mysql-connector-python or the `mysql` command line client. + +## Project structure + +- `docs/` - the wiki pages, one Markdown file per page. `docs/es/` and `docs/cn/` hold the translations, `docs/archive/` the archived pages. +- `_includes/` - shared HTML: the sidebar (`azerothcore/sidebar.html`) and the notice boxes. +- `_layouts/`, `_sass/`, `assets/` - page templates, styling and scripts. +- `images/` - images used in the pages. +- `_config.yml` - the Jekyll configuration. +- `.env-files/`, `docker-compose.yml`, `tools/` - what is needed to run the site locally. + +## Adding content + +- Read the [Wiki Standards](https://www.azerothcore.org/wiki/wiki-standards) first. +- **New or changed page**: add or edit a Markdown file in `docs/`. `docs/my-page.md` is published as `/wiki/my-page`. +- **Database table page**: follow the [Database Table Template](https://www.azerothcore.org/wiki/database-table-template). Then run `python tools/update_table_lists.py` to add it to the lists (see [Tools](#tools)). +- **Sidebar**: edit `_includes/azerothcore/sidebar.html`. + +## Deployment + +The site is built and published from the `master` branch. There is no manual deploy step. diff --git a/.github/workflows/generate-command-table.yml b/.github/workflows/generate-command-table.yml new file mode 100644 index 000000000..85d2f3b42 --- /dev/null +++ b/.github/workflows/generate-command-table.yml @@ -0,0 +1,26 @@ +name: generate-command-table-from-db +on: + workflow_dispatch: + +jobs: + generate-command-table: + permissions: write-all + runs-on: ubuntu-24.04 + steps: + - name: checkout + uses: actions/checkout@v4 + + - name: "run scripts" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git clone https://github.com/azerothcore/acore-docker + cd acore-docker + docker compose up -d + cd .. + mysqldump -u root -ppassword -P 63306 -h 127.0.0.1 acore_world command > command_table.sql + zip command_table.sql.zip command_table.sql + revision=`mysql -u root -ppassword -P 63306 -h 127.0.0.1 -s -N -e "SELECT substring_index(substring_index(revision, 'rev. ', -1), '+ 2', 1) FROM acore_auth.uptime ORDER BY starttime DESC LIMIT 1;"` + release_name=$(date '+%Y-%m-%d_%H-%M-%S') + gh release create $release_name --title "$release_name" --notes "Revision: [$revision](https://github.com/azerothcore/azerothcore-wotlk/commit/$revision)" + gh release upload $release_name "command_table.sql.zip" \ No newline at end of file diff --git a/.gitignore b/.gitignore index a8d179c4c..97d9f8534 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,13 @@ _site Gemfile.*.lock Gemfile.lock +Gemfile +.jekyll-metadata .sass-cache .DS_Store .idea/* .claude/ +.theme-cache/ +tools/logs/ diff --git a/_config.local.en.yml b/_config.local.en.yml new file mode 100644 index 000000000..75c6a01b5 --- /dev/null +++ b/_config.local.en.yml @@ -0,0 +1,2 @@ +# Used by tools/wiki unless it is run with "all": leaves out the translations to keep the build short. +exclude: ['wiki', 'tools', 'Gemfile', 'Gemfile.lock', 'docs/es', 'docs/cn'] diff --git a/_config.local.yml b/_config.local.yml new file mode 100644 index 000000000..9f5df12a0 --- /dev/null +++ b/_config.local.yml @@ -0,0 +1,9 @@ +# Local previews only (used by tools/wiki). +# _config.yml's plugins without jekyll-redirect-from, which breaks pages on Windows and macOS. +plugins: + - jekyll-feed + - jekyll-seo-tag + - jekyll-sitemap + - jekyll-avatar + - jemoji + - jekyll-mentions diff --git a/_config.yml b/_config.yml index 494ba9d04..03b34e3a2 100644 --- a/_config.yml +++ b/_config.yml @@ -137,7 +137,7 @@ plugins: - jemoji - jekyll-mentions -exclude: ['wiki'] +exclude: ['wiki', 'tools', 'Gemfile', 'Gemfile.lock'] # @@ -164,7 +164,7 @@ inc_before_header : inc_after_header : inc_before_tail : inc_after_tail : -inc_before_tools : +inc_before_tools : "azerothcore/languages.html" inc_after_tools : inc_before_page_list : "azerothcore/sidebar.html" diff --git a/_includes/azerothcore/languages.html b/_includes/azerothcore/languages.html new file mode 100644 index 000000000..f6450b58c --- /dev/null +++ b/_includes/azerothcore/languages.html @@ -0,0 +1,19 @@ +{% assign lang_prefix = page.url | slice: 0, 4 %} +{% if lang_prefix == "/es/" or lang_prefix == "/cn/" %} +{% assign lang_base = page.url | remove_first: lang_prefix %} +{% assign lang_current = lang_prefix | remove: "/" %} +{% else %} +{% assign lang_base = page.url | remove_first: "/" %} +{% assign lang_current = "en" %} +{% endif %} +{% assign lang_en_url = "/" | append: lang_base %} +{% assign lang_es_url = "/es/" | append: lang_base %} +{% assign lang_cn_url = "/cn/" | append: lang_base %} +{% assign lang_en_page = site.pages | where: "url", lang_en_url | first %} +{% assign lang_es_page = site.pages | where: "url", lang_es_url | first %} +{% assign lang_cn_page = site.pages | where: "url", lang_cn_url | first %} +
This project is maintained by AzerothCore
+Hosted on GitHub Pages - Powered by Git-Wiki version: {{ version }}
+ {% if site.github.repository_url %} +Currently being hosted from repo {{ site.github.repository_nwo }}
+ {% endif %} +