d2rdoc

This is an augmented version of Blizzard's original documentation for Diablo II: Resurrected, as they introduced in 3.0's Reign of the Warlock expansion.

You can see the live site here!

The primary purpose for this is to provide a platform for guides (as they pertain to Diablo II: Resurrected) as well as annotations to the original fileguide.

Running the Scripts

The python/update_fileguide.py script is the main entry point. It requires Python 3.10+.

python python/update_fileguide.py -a <action> -data <data-dir> [-html <html-dir>] [-p]

Arguments:

Argument	Description
-a	Action: all, files, search, notes, guides, or validate
-data	Path to the directory containing the data files (e.g. data)
-html	Path to the directory containing the generated .html files (e.g. files). Required for all and files actions.
-p	Optional. Use Perforce (p4) to check out and add files before writing.

Actions:

• files — Syncs data/files/*.js with data/dataguidefieldexport.json (adding missing fields/files), then regenerates all .html pages in files/.
• search — Rebuilds data/search.js from the current state of data/files/*.js.
• notes — Converts contrib/community-notes.json into data/community-notes.js for the site to load.
• guides — Converts Markdown files in contrib/guides/ into HTML pages in guides/ and updates the sidebar index. Requires python-markdown (see Guides below).
• validate — Validates all .js data files: checks field types, reference links, required properties, and consistency with dataguidefieldexport.json.
• all — Runs files, search, notes, guides, and validate in sequence.

Common invocations:

# Full rebuild from repo root
python python/update_fileguide.py -a all -data data -html files

# Only rebuild HTML pages (after editing .js files)
python python/update_fileguide.py -a files -data data -html files

# Only rebuild search index
python python/update_fileguide.py -a search -data data

# Only rebuild community notes (after editing contrib/community-notes.json)
python python/update_fileguide.py -a notes -data data

# Only rebuild guides (after editing contrib/guides/*.md or contrib/guides.json)
python python/update_fileguide.py -a guides -data data

# Validate without writing any files
python python/update_fileguide.py -a validate -data data

Modding Community Contributions

Community Notes

Community notes let contributors add supplemental information to any file or field without modifying the authoritative Blizzard-authored data files. Notes appear in the generated HTML below the official content in a distinct blue colour.

Source File

Edit contrib/community-notes.json. This file is checked into the repository and is the only file you need to change. After editing, regenerate the JS output with:

python python/update_fileguide.py -a notes -data data

Format

The file contains a JSON array. Each entry targets one data file and can carry a file-level note, field-level notes, or both.

[
    {
        "file": "armor",
        "note": "Optional note shown below the file overview.",
        "fields": [
            {
                "name": "minac",
                "note": "Optional note shown below this field's description."
            }
        ]
    }
]

Property	Description
file	The file key to annotate (matches data/files/<key>.js, case-insensitive).
note	File-level note displayed below the overview. Optional.
fields	Array of field annotations. Optional.
fields[].name	The field name to annotate (matches name in the data file, case-insensitive).
fields[].note	Note displayed below the field's description, table, and appendField.

Notes support the same reference link syntax as regular descriptions — $!page!$, $!page#element!$, and $!#element!$ all work.

Guides

Guides are long-form Markdown documents authored by contributors. They are built into HTML pages and appear under a Guides accordion section in the left sidebar.

Guides require the python-markdown package. If it is not installed, the -a guides action prints a warning and exits cleanly — no HTML is generated and the sidebar is not updated.

pip install markdown

• contrib/guides.json — metadata list (checked into git)
• contrib/guides/*.md — Markdown source files (checked into git)
• guides/*.html — generated output (gitignored, regenerated by the script)

guides.json Format

[
    {
        "filename": "getting-started.md",
        "title": "Getting Started",
        "description": "An introduction to modding D2R data files.",
        "author": "Community"
    }
]

Property	Required	Description
filename	Yes	The .md file in contrib/guides/ to build.
title	Yes	Display name shown in the sidebar and as the page <h1>.
description	No	Short summary rendered below the title on the page.
author	No	Author credit rendered below the title on the page.

Standard Markdown plus GFM-style tables and fenced code blocks (```) work out of the box.

Contribution Guidelines