A guide is Everloot's own advice on one talent plan for one class: who it is for, why it fits an activity, how to play it and what is not known yet. This page is the contract every guide meets. How to write one is in kb/guides/README.md.
The contract is code, in three places:
| File | What it holds |
|---|---|
kb/src/guides/guide.ts |
The schema: every field, and the rules the fields keep with each other. Every reader parses a guide here, so a reader that only parses still refuses a guide that breaks them. |
kb/src/guides/check.ts |
The check: the rules that need the talent trees, the wiki, the other guides, or the guides as they were before a change. Each problem names its file and line. |
web/src/lib/guides.ts |
The site's reader. |
A guide's status is draft or published. People set it, through review, and nothing automatic changes it.
How current a published guide still is (whether the game build it was reviewed on is still the live one, whether
anything its plan depends on has changed) is a separate question. Readers work it out from the data. It is not a
field: a file that declares one fails the check as an unknown field. A newer game build does not make a guide wrong
by itself and never rewrites it. When a change to a talent tree means a published plan no longer fits, the check
fails until a person acts, with a new reviewed version or with status: draft to withdraw the guide.
version is the version the file holds. history lists every published version, oldest first, as
{ version, on, by, build, note }: the review that published it, and what changed.
- A published guide's
versionis the last entry inhistory, and that entry is the review inreviewed. - A draft holds the last published version (a withdrawn guide) or the next one (a revision in progress). A guide that was never published is version 1, with an empty history.
- Versions count up from 1, one entry each, and their dates never go back.
A file holds one version, and readers go by its status, so a draft is off the site either way. A revision merged to main as a draft takes the published version down until the revision is published. Keep a revision on its branch until it is reviewed and merge it as published; set a published guide to draft only to withdraw it.
Given the guides as they were before a change (previous; for a pull request, a copy of kb/guides at its base),
the check also holds published versions to what they were:
- A published version that changes in any way, its review date included, fails. The change is the next version,
with its own review in
history. - Versions never go down, and history only grows: an entry is never edited or removed.
- A guide that has been published keeps its slug, so its address stays, and its file stays. To withdraw it, set
status: draft; its history stays with it. - A guide that was never published may change or go.
- A file in that copy that no longer reads (bad YAML, or front matter today's schema refuses) fails the check, with its line, so an edit or a deletion is never let through unchecked.
npm run kb -- guide-check --previous <folder> passes the check that copy. CI runs it on every pull request with
kb/guides as it was at the base, and on a push to main with the folder as it was before the push. The base's files
are read from git as data, never checked out or run. A base without the folder is compared with an empty one; a base
that cannot be fetched or read fails the step, so the comparison is never skipped.
reviewed is { by, on, build }: who reviewed the version the file holds, on which day, and the game build they
checked it against. A published guide has one. The date is not after today, and only the person who actually reviewed
that version is named.
code and the optional code2 are talent share codes; order and order2 are
the spend order tokens that ride with them. Against the class's talent tree, as the calculator reads it:
- A code is the guide's class and places exactly as written: every talent is on the tree, every rank is within its maximum and the point rules allow every point.
- It spends no more points than the levels give, and its last point arrives by
levels.to, which is within the tree's levels. - An order reads with its code and is legal point by point: each point could be taken where it stands.
- A published guide carries only orders a player planned (
O1p-). A provisional order a tool generated (O1g-) stays usable in personal plans and may sit in a draft, but is never published as a reviewed order. - A guide without an order is valid. Readers show its order as unknown and never derive one.
- The plan lives in the front matter. A link in the body that carries
plan=,plan2=,order=ororder2=, or is a build link (/tools/talents/<class>/b/…,/b/…), fails, so every plan a guide shows is one the check has read.
The body has four ## sections, in order: Who it is for, Why this plan, How to play it, What we do not know yet. On
a published guide each one has words of our own, and the guide has at least 150 words of its own prose, the same
floor as a wiki page. The floor is there to catch a guide that says nothing. It is not a target, and it promises
nothing about search.
Numbers in the prose are allowed. A guide talks about levels and points, so the check does not refuse them; the reviewer checks each one against its evidence.
sourcesare Blizzard's own posts, on worldofwarcraft.blizzard.com, news.blizzard.com and the US and EU forums. Each is linked in the body where the claim it supports is made, and records the day it was checked. Every link off the site is a listed source.- Everything else a guide says comes from Everloot's own data, linked on the site: database tokens, wiki pages, tool
pages, and the
/changespage of a Blizzard post shown there. Other sites' guides are not sources, and nothing is copied from them (data policy). The narrow exceptions in the source ledger stay where it scopes them. [[slug]],/wiki/and/guides/links name pages that exist, and a published guide links only to published pages.
A draft, or a file that fails the schema, is shown nowhere. In the site's reader, publishedGuides, publishedGuide
and guidesFor return published guides only, and guidesFor narrows them by class, activity, role and level.
Anything that shows guides reads them through these.
/guides lists the published guides by class, and /guides/<slug> shows one: its review, its plan, its four
sections, its sources and every published version. A draft, or a file that fails the schema, is a 404 there, on the
guide's social card and in the sitemap. A link in a guide's body to a guide that is not published is drawn as its
words alone, also through a version's prefix such as /beta, so no draft's address shows even if one reached main.
write is never a guide's slug: /guides/write is the page where a player writes a community guide, so a guide by
that name could never be shown. The schema refuses it (RESERVED_GUIDE_SLUGS in
kb/src/guides/guide.ts), draft or published, and the check names the slug's line.
How current a guide is, its page works out each time it is rebuilt, at most once an hour
(web/src/lib/guide-freshness.ts), and says why when it is not current:
- Broken: its plan no longer fits the talent tree, in the calculator's own words: a talent is gone or its rank is cut, the order breaks the tree's rules, or the tree's points or the guide's levels no longer hold the plan. A second set is broken, too, when it opens at a level after the guide's levels end. Copy for addon is off for that set.
- Stale: the build watch's change records show a change to the plan's talents, or to the levels points arrive at, after the build the guide was reviewed against, whatever build its code was made on. A missing or incomplete record is never read as a change. The note lists only the changes after that build; one at or before it is a change the review saw.
- Review due: 60 days have passed since the last review, or a live build is newer than the one it was reviewed against.
The page reads the codes, their builds and the review as the file has them, and never re-stamps one. A person acts,
with a new reviewed version or with status: draft.
A guide is indexed, and listed in the sitemap dated by its review, only while it is published and reviewed, has the 150 words of its own, and is neither stale nor broken. A filtered list of guides is noindex.
The page's calculator link carries both sets exactly as the file stores them. Copy for addon copies one set as a
full calculator link, #plan=<code>&order=<order> for the first and #plan2=<code2>&order2=<order2> for the second;
in the game, /everloot → Talents → paste → Import. Addon 0.3.12 loads the talents from it, not the order.