Merge branch 'develop' into stable

4 files changed, 862 insertions, 0 deletions

diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md
new file mode 100644
index 00000000..a33480ad
--- /dev/null
+++ b/docs/technical/mod-package.md
@@ -0,0 +1,366 @@
+← [SMAPI](../README.md)
+
+The **mod build package** is an open-source NuGet package which automates the MSBuild configuration
+for SMAPI mods and related tools. The package is fully compatible with Linux, Mac, and Windows.
+
+## Contents
+* [Use](#use)
+* [Features](#features)
+  * [Detect game path](#detect-game-path)
+  * [Add assembly references](#add-assembly-references)
+  * [Copy files into the `Mods` folder and create release zip](#copy-files-into-the-mods-folder-and-create-release-zip)
+  * [Launch or debug game](#launch-or-debug-game)
+  * [Preconfigure common settings](#preconfigure-common-settings)
+  * [Add code warnings](#add-code-warnings)
+* [Code warnings](#code-warnings)
+* [Special cases](#special-cases)
+  * [Custom game path](#custom-game-path)
+  * [Non-mod projects](#non-mod-projects)
+* [For SMAPI developers](#for-smapi-developers)
+* [Release notes](#release-notes)
+
+## Use
+1. Create an empty library project.
+2. Reference the [`Pathoschild.Stardew.ModBuildConfig` NuGet package](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig).
+3. [Write your code](https://stardewvalleywiki.com/Modding:Creating_a_SMAPI_mod).
+4. Compile on any platform.
+5. Run the game to play with your mod.
+
+## Features
+The package automatically makes the changes listed below. In some cases you can configure how it
+works by editing your mod's `.csproj` file, and adding the given properties between the first
+`<PropertyGroup>` and `</PropertyGroup>` tags.
+
+### Detect game path
+The package finds your game folder by scanning the default install paths and Windows registry. It
+adds two MSBuild properties for use in your `.csproj` file if needed:
+
+property | description
+-------- | -----------
+`$(GamePath)` | The absolute path to the detected game folder.
+`$(GameExecutableName)` | The game's executable name for the current OS (`Stardew Valley` on Windows, or `StardewValley` on Linux/Mac).
+
+If you get a build error saying it can't find your game, see [_set the game path_](#set-the-game-path).
+
+### Add assembly references
+The package adds assembly references to SMAPI, Stardew Valley, xTile, and MonoGame (Linux/Mac) or XNA
+Framework (Windows). It automatically adjusts depending on which OS you're compiling it on.
+
+The assemblies aren't copied to the build output, since mods loaded by SMAPI won't need them. For
+non-mod projects like unit tests, you can set this property:
+```xml
+<CopyModReferencesToBuildOutput>true</CopyModReferencesToBuildOutput>
+```
+
+If your mod uses [Harmony](https://github.com/pardeike/Harmony) (not recommended for most mods),
+the package can add a reference to SMAPI's Harmony DLL for you:
+```xml
+<EnableHarmony>true</EnableHarmony>
+```
+
+### Copy files into the `Mods` folder and create release zip
+<dl>
+<dt>Files considered part of your mod</dt>
+<dd>
+
+These files are selected by default: `manifest.json`,
+[`i18n` files](https://stardewvalleywiki.com/Modding:Translations) (if any), the `assets` folder
+(if any), and all files in the build output. You can select custom files by [adding them to the
+build output](https://stackoverflow.com/a/10828462/262123). (If your project references another mod,
+make sure the reference is [_not_ marked 'copy local'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx).)
+
+You can deselect a file by removing it from the build output. For a default file, you can set the
+property below to a comma-delimited list of regex patterns to ignore. For crossplatform
+compatibility, you should replace path delimiters with `[/\\]`.
+
+```xml
+<IgnoreModFilePatterns>\.txt$, \.pdf$, assets[/\\]paths.png</IgnoreModFilePatterns>
+```
+
+</dd>
+<dt>Copy files into the `Mods` folder</dt>
+<dd>
+
+The package copies the selected files into your game's `Mods` folder when you rebuild the code,
+with a subfolder matching the mod's project name.
+
+You can change the folder name:
+```xml
+<ModFolderName>YourModName</ModFolderName>
+```
+
+Or disable deploying the files:
+```xml
+<EnableModDeploy>false</EnableModDeploy>
+```
+
+</dd>
+<dt>Create release zip</dt>
+<dd>
+
+The package adds a zip file in your project's `bin` folder when you rebuild the code, in the format
+recommended for sites like Nexus Mods. The zip filename can be changed using `ModFolderName` above.
+
+You can change the folder path where the zip is created:
+```xml
+<ModZipPath>$(SolutionDir)\_releases</ModZipPath>
+```
+
+Or disable zip creation:
+```xml
+<EnableModZip>false</EnableModZip>
+```
+
+</dd>
+</dl>
+
+### Launch or debug game
+On Windows only, the package configures Visual Studio so you can launch the game and attach a
+debugger using _Debug > Start Debugging_ or _Debug > Start Without Debugging_. This lets you [set
+breakpoints](https://docs.microsoft.com/en-us/visualstudio/debugger/using-breakpoints?view=vs-2019)
+in your code while the game is running, or [make simple changes to the mod code without needing to
+restart the game](https://docs.microsoft.com/en-us/visualstudio/debugger/edit-and-continue?view=vs-2019).
+
+This is disabled on Linux/Mac due to limitations with the Mono wrapper.
+
+To disable game debugging (only needed for some non-mod projects):
+
+```xml
+<EnableGameDebugging>false</EnableGameDebugging>
+```
+
+### Preconfigure common settings
+The package also automatically enables PDB files (so error logs show line numbers for simpler
+debugging), and enables support for the simplified `.csproj` format.
+
+### Add code warnings
+The package runs code analysis on your mod and raises warnings for some common errors or pitfalls.
+See [_code warnings_](#code-warnings) for more info.
+
+## Code warnings
+### Overview
+The NuGet package adds code warnings in Visual Studio specific to Stardew Valley. For example:  
+![](screenshots/code-analyzer-example.png)
+
+You can hide the warnings using the warning ID (shown under 'code' in the Error List). See...
+* [for specific code](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-pragma-warning);
+* for a method using this attribute:
+  ```cs
+  [System.Diagnostics.CodeAnalysis.SuppressMessage("SMAPI.CommonErrors", "AvoidNetField")]
+  ```
+* for an entire project:
+  1. Expand the _References_ node for the project in Visual Studio.
+  2. Right-click on _Analyzers_ and choose _Open Active Rule Set_.
+  4. Expand _StardewModdingAPI.ModBuildConfig.Analyzer_ and uncheck the warnings you want to hide.
+
+See below for help with each specific warning.
+
+### Avoid implicit net field cast
+Warning text:
+> This implicitly converts '{{expression}}' from {{net type}} to {{other type}}, but
+> {{net type}} has unintuitive implicit conversion rules. Consider comparing against the actual
+> value instead to avoid bugs.
+
+Stardew Valley uses net types (like `NetBool` and `NetInt`) to handle multiplayer sync. These types
+can implicitly convert to their equivalent normal values (like `bool x = new NetBool()`), but their
+conversion rules are unintuitive and error-prone. For example,
+`item?.category == null && item?.category != null` can both be true at once, and
+`building.indoors != null` can be true for a null value.
+
+Suggested fix:
+* Some net fields have an equivalent non-net property like `monster.Health` (`int`) instead of
+  `monster.health` (`NetInt`). The package will add a separate [AvoidNetField](#avoid-net-field) warning for
+  these. Use the suggested property instead.
+* For a reference type (i.e. one that can contain `null`), you can use the `.Value` property:
+  ```c#
+  if (building.indoors.Value == null)
+  ```
+  Or convert the value before comparison:
+  ```c#
+  GameLocation indoors = building.indoors;
+  if(indoors == null)
+     // ...
+  ```
+* For a value type (i.e. one that can't contain `null`), check if the object is null (if applicable)
+  and compare with `.Value`:
+  ```cs
+  if (item != null && item.category.Value == 0)
+  ```
+
+### Avoid net field
+Warning text:
+> '{{expression}}' is a {{net type}} field; consider using the {{property name}} property instead.
+
+Your code accesses a net field, which has some unusual behavior (see [AvoidImplicitNetFieldCast](#avoid-implicit-net-field-cast)).
+This field has an equivalent non-net property that avoids those issues.
+
+Suggested fix: access the suggested property name instead.
+
+### Avoid obsolete field
+Warning text:
+> The '{{old field}}' field is obsolete and should be replaced with '{{new field}}'.
+
+Your code accesses a field which is obsolete or no longer works. Use the suggested field instead.
+
+## Special cases
+### Custom game path
+The package usually detects where your game is installed automatically. If it can't find your game
+or you have multiple installs, you can specify the path yourself. There's two ways to do that:
+
+* **Option 1: global game path (recommended).**  
+  _This will apply to every project that uses the package._
+
+  1. Get the full folder path containing the Stardew Valley executable.
+  2. Create this file:
+  
+     platform  | path
+     --------- | ----
+     Linux/Mac | `~/stardewvalley.targets`
+     Windows   | `%USERPROFILE%\stardewvalley.targets`
+
+  3. Save the file with this content:
+
+     ```xml
+     <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+        <PropertyGroup>
+          <GamePath>PATH_HERE</GamePath>
+        </PropertyGroup>
+     </Project>
+     ```
+
+  4. Replace `PATH_HERE` with your game path.
+
+* **Option 2: path in the project file.**  
+  _You'll need to do this for each project that uses the package._
+
+  1. Get the folder path containing the Stardew Valley `.exe` file.
+  2. Add this to your `.csproj` file under the `<Project` line:
+
+     ```xml
+     <PropertyGroup>
+       <GamePath>PATH_HERE</GamePath>
+     </PropertyGroup>
+     ```
+
+  3. Replace `PATH_HERE` with your custom game install path.
+
+The configuration will check your custom path first, then fall back to the default paths (so it'll
+still compile on a different computer).
+
+You access the game path via `$(GamePath)` in MSBuild properties, if you need to reference another
+file in the game folder.
+
+### Non-mod projects
+You can use the package in non-mod projects too (e.g. unit tests or framework DLLs). Just disable
+the mod-related package features:
+
+```xml
+<EnableGameDebugging>false</EnableGameDebugging>
+<EnableModDeploy>false</EnableModDeploy>
+<EnableModZip>false</EnableModZip>
+```
+
+If you need to copy the referenced DLLs into your build output, add this too:
+```xml
+<CopyModReferencesToBuildOutput>true</CopyModReferencesToBuildOutput>
+```
+
+## For SMAPI developers
+The mod build package consists of three projects:
+
+project                                           | purpose
+------------------------------------------------- | ----------------
+`StardewModdingAPI.ModBuildConfig`                | Configures the build (references, deploying the mod files, setting up debugging, etc).
+`StardewModdingAPI.ModBuildConfig.Analyzer`       | Adds C# analyzers which show code warnings in Visual Studio.
+`StardewModdingAPI.ModBuildConfig.Analyzer.Tests` | Unit tests for the C# analyzers.
+
+To prepare a build of the NuGet package:
+1. Install the [NuGet CLI](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools#nugetexe-cli).
+1. Change the version and release notes in `package.nuspec`.
+2. Rebuild the solution in _Release_ mode.
+3. Open a terminal in the `bin/Pathoschild.Stardew.ModBuildConfig` package and run this command:
+   ```bash
+   nuget.exe pack
+   ```
+
+That will create a `Pathoschild.Stardew.ModBuildConfig-<version>.nupkg` file in the same directory
+which can be uploaded to NuGet or referenced directly.
+
+## Release notes
+### Upcoming release
+* Updated for SMAPI 3.0 and Stardew Valley 1.4.
+* Added automatic support for `assets` folders.
+* Added `$(GameExecutableName)` MSBuild variable.
+* Added support for projects using the simplified `.csproj` format.
+* Added option to disable game debugging config.
+* Added `.pdb` files to builds by default (to enable line numbers in error stack traces).
+* Added optional Harmony reference.
+* Fixed `Newtonsoft.Json.pdb` included in release zips when Json.NET is referenced directly.
+* Fixed `<IgnoreModFilePatterns>` not working for `i18n` files.
+* Dropped support for older versions of SMAPI and Visual Studio.
+
+### 2.2
+* Added support for SMAPI 2.8+ (still compatible with earlier versions).
+* Added default game paths for 32-bit Windows.
+* Fixed valid manifests marked invalid in some cases.
+
+### 2.1
+* Added support for Stardew Valley 1.3.
+* Added support for non-mod projects.
+* Added C# analyzers to warn about implicit conversions of Netcode fields in Stardew Valley 1.3.
+* Added option to ignore files by regex pattern.
+* Added reference to new SMAPI DLL.
+* Fixed some game paths not detected by NuGet package.
+
+### 2.0.2
+* Fixed compatibility issue on Linux.
+
+### 2.0.1
+* Fixed mod deploy failing to create subfolders if they don't already exist.
+
+### 2.0
+* Added: mods are now copied into the `Mods` folder automatically (configurable).
+* Added: release zips are now created automatically in your build output folder (configurable).
+* Added: mod deploy and release zips now exclude Json.NET automatically, since it's provided by SMAPI.
+* Added mod's version to release zip filename.
+* Improved errors to simplify troubleshooting.
+* Fixed release zip not having a mod folder.
+* Fixed release zip failing if mod name contains characters that aren't valid in a filename.
+
+### 1.7.1
+* Fixed issue where i18n folders were flattened.
+* The manifest/i18n files in the project now take precedence over those in the build output if both
+  are present.
+
+### 1.7
+* Added option to create release zips on build.
+* Added reference to XNA's XACT library for audio-related mods.
+
+### 1.6
+* Added support for deploying mod files into `Mods` automatically.
+* Added a build error if a game folder is found, but doesn't contain Stardew Valley or SMAPI.
+
+### 1.5
+* Added support for setting a custom game path globally.
+* Added default GOG path on Mac.
+
+### 1.4
+* Fixed detection of non-default game paths on 32-bit Windows.
+* Removed support for SilVerPLuM (discontinued).
+* Removed support for overriding the target platform (no longer needed since SMAPI crossplatforms
+  mods automatically).
+
+### 1.3
+* Added support for non-default game paths on Windows.
+
+### 1.2
+* Exclude game binaries from mod build output.
+
+### 1.1
+* Added support for overriding the target platform.
+
+### 1.0
+* Initial release.
+* Added support for detecting the game path automatically.
+* Added support for injecting XNA/MonoGame references automatically based on the OS.
+* Added support for mod builders like SilVerPLuM.
diff --git a/docs/technical/screenshots/code-analyzer-example.png b/docs/technical/screenshots/code-analyzer-example.png
new file mode 100644
index 00000000..de38f643
--- /dev/null
+++ b/docs/technical/screenshots/code-analyzer-example.png
diff --git a/docs/technical/smapi.md b/docs/technical/smapi.md
new file mode 100644
index 00000000..96f7dff5
--- /dev/null
+++ b/docs/technical/smapi.md
@@ -0,0 +1,116 @@
+&larr; [README](../README.md)
+
+This file provides more technical documentation about SMAPI. If you only want to use or create
+mods, this section isn't relevant to you; see the main README to use or create mods.
+
+This document is about SMAPI itself; see also [mod build package](mod-package.md) and
+[web services](web.md).
+
+# Contents
+* [Customisation](#customisation)
+  * [Configuration file](#configuration-file)
+  * [Command-line arguments](#command-line-arguments)
+  * [Compile flags](#compile-flags)
+* [For SMAPI developers](#for-smapi-developers)
+  * [Compiling from source](#compiling-from-source)
+  * [Debugging a local build](#debugging-a-local-build)
+  * [Preparing a release](#preparing-a-release)
+* [Release notes](#release-notes)
+
+## Customisation
+### Configuration file
+You can customise the SMAPI behaviour by editing the `smapi-internal/config.json` file in your game
+folder.
+
+Basic fields:
+
+field             | purpose
+----------------- | -------
+`DeveloperMode`   | Default `false` (except in _SMAPI for developers_ releases). Whether to enable features intended for mod developers (mainly more detailed console logging).
+`CheckForUpdates` | Default `true`. Whether SMAPI should check for a newer version when you load the game. If a new version is available, a small message will appear in the console. This doesn't affect the load time even if your connection is offline or slow, because it happens in the background.
+`VerboseLogging`  | Default `false`. Whether SMAPI should log more information about the game context.
+`ModData`         | Internal metadata about SMAPI mods. Changing this isn't recommended and may destabilise your game. See documentation in the file.
+
+### Command-line arguments
+The SMAPI installer recognises three command-line arguments:
+
+argument | purpose
+-------- | -------
+`--install` | Preselects the install action, skipping the prompt asking what the user wants to do.
+`--uninstall` | Preselects the uninstall action, skipping the prompt asking what the user wants to do.
+`--game-path "path"` | Specifies the full path to the folder containing the Stardew Valley executable, skipping automatic detection and any prompt to choose a path. If the path is not valid, the installer displays an error.
+
+SMAPI itself recognises two arguments **on Windows only**, but these are intended for internal use
+or testing and may change without warning. On Linux/Mac, see _environment variables_ below.
+
+argument | purpose
+-------- | -------
+`--no-terminal` | SMAPI won't write anything to the console window. (Messages will still be written to the log file.)
+`--mods-path` | The path to search for mods, if not the standard `Mods` folder. This can be a path relative to the game folder (like `--mods-path "Mods (test)"`) or an absolute path.
+
+### Environment variables
+The above SMAPI arguments don't work on Linux/Mac due to the way the game launcher works. You can
+set temporary environment variables instead. For example:
+> SMAPI_MODS_PATH="Mods (multiplayer)" /path/to/StardewValley
+
+environment variable | purpose
+-------------------- | -------
+`SMAPI_NO_TERMINAL` | Equivalent to `--no-terminal` above.
+`SMAPI_MODS_PATH` | Equivalent to `--mods-path` above.
+
+
+### Compile flags
+SMAPI uses a small number of conditional compilation constants, which you can set by editing the
+`<DefineConstants>` element in `SMAPI.csproj`. Supported constants:
+
+flag | purpose
+---- | -------
+`SMAPI_FOR_WINDOWS` | Whether SMAPI is being compiled on Windows for players on Windows. Set automatically in `crossplatform.targets`.
+
+## For SMAPI developers
+### Compiling from source
+Using an official SMAPI release is recommended for most users.
+
+SMAPI uses some C# 7 code, so you'll need at least
+[Visual Studio 2017](https://www.visualstudio.com/vs/community/) on Windows,
+[MonoDevelop 7.0](https://www.monodevelop.com/) on Linux,
+[Visual Studio 2017 for Mac](https://www.visualstudio.com/vs/visual-studio-mac/), or an equivalent
+IDE to compile it. It uses build configuration derived from the
+[crossplatform mod config](https://github.com/Pathoschild/Stardew.ModBuildConfig#readme) to detect
+your current OS automatically and load the correct references. Compile output will be placed in a
+`bin` folder at the root of the git repository.
+
+### Debugging a local build
+Rebuilding the solution in debug mode will copy the SMAPI files into your game folder. Starting
+the `SMAPI` project with debugging from Visual Studio (on Mac or Windows) will launch SMAPI with
+the debugger attached, so you can intercept errors and step through the code being executed. This
+doesn't work in MonoDevelop on Linux, unfortunately.
+
+### Preparing a release
+To prepare a crossplatform SMAPI release, you'll need to compile it on two platforms. See
+[crossplatforming info](https://stardewvalleywiki.com/Modding:Modder_Guide/Test_and_Troubleshoot#Testing_on_all_platforms)
+on the wiki for the first-time setup.
+
+1. Update the version number in `.root/build/common.targets` and `Constants::Version`. Make sure
+  you use a [semantic version](https://semver.org). Recommended format:
+
+   build type | format                   | example
+   :--------- | :----------------------- | :------
+   dev build  | `<version>-alpha.<date>` | `3.0-alpha.20171230`
+   prerelease | `<version>-beta.<count>` | `3.0-beta.2`
+   release    | `<version>`              | `3.0`
+
+2. In Windows:
+   1. Rebuild the solution in Release mode.
+   2. Copy `windows-install.*` from `bin/SMAPI installer` and `bin/SMAPI installer for developers` to
+      Linux/Mac.
+
+3. In Linux/Mac:
+   1. Rebuild the solution in Release mode.
+   2. Add the `windows-install.*` files to the `bin/SMAPI installer` and
+      `bin/SMAPI installer for developers` folders.
+   3. Rename the folders to `SMAPI <version> installer` and `SMAPI <version> installer for developers`.
+   4. Zip the two folders.
+
+## Release notes
+See [release notes](../release-notes.md).
diff --git a/docs/technical/web.md b/docs/technical/web.md
new file mode 100644
index 00000000..78d93625
--- /dev/null
+++ b/docs/technical/web.md
@@ -0,0 +1,380 @@
+&larr; [README](../README.md)
+
+**SMAPI.Web** contains the code for the `smapi.io` website, including the mod compatibility list
+and update check API.
+
+## Contents
+* [Log parser](#log-parser)
+* [JSON validator](#json-validator)
+* [Web API](#web-api)
+* [Short URLs](#short-urls)
+* [For SMAPI developers](#for-smapi-developers)
+  * [Local development](#local-development)
+  * [Deploying to Amazon Beanstalk](#deploying-to-amazon-beanstalk)
+
+## Log parser
+The log parser provides a web UI for uploading, parsing, and sharing SMAPI logs. The logs are
+persisted in a compressed form to Pastebin. The log parser lives at https://log.smapi.io.
+
+## JSON validator
+### Overview
+The JSON validator provides a web UI for uploading and sharing JSON files, and validating them as
+plain JSON or against a predefined format like `manifest.json` or Content Patcher's `content.json`.
+The JSON validator lives at https://json.smapi.io.
+
+### Schema file format
+Schema files are defined in `wwwroot/schemas` using the [JSON Schema](https://json-schema.org/)
+format. The JSON validator UI recognises a superset of the standard fields to change output:
+
+<dl>
+<dt>Documentation URL</dt>
+<dd>
+
+The root schema may have a `@documentationURL` field, which is a web URL for the user
+documentation:
+```js
+"@documentationUrl": "https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest"
+```
+
+If present, this is shown in the JSON validator UI.
+
+</dd>
+<dt>Error messages</dt>
+<dd>
+
+Any part of the schema can define an `@errorMessages` field, which overrides matching schema
+errors. You can override by error code (recommended), or by error type and a regex pattern matched
+against the error message (more fragile):
+
+```js
+// by error type
+"pattern": "^[a-zA-Z0-9_.-]+\\.dll$",
+"@errorMessages": {
+   "pattern": "Invalid value; must be a filename ending with .dll."
+}
+```
+```js
+// by error type + message pattern
+"@errorMessages": {
+   "oneOf:valid against no schemas": "Missing required field: EntryDll or ContentPackFor.",
+   "oneOf:valid against more than one schema": "Can't specify both EntryDll or ContentPackFor, they're mutually exclusive."
+}
+```
+
+Error messages may contain special tokens:
+
+* The `@value` token is replaced with the error's value field. This is usually (but not always) the
+  original field value.
+* When an error has child errors, by default they're flattened into one message:
+  ```
+  line | field      | error
+  ---- | ---------- | -------------------------------------------------------------------------
+  4    | Changes[0] | JSON does not match schema from 'then'.
+       |            |   ==> Changes[0].ToArea.Y: Invalid type. Expected Integer but got String.
+       |            |   ==> Changes[0].ToArea: Missing required fields: Height.
+  ```
+
+  If you set the message for an error to `$transparent`, the parent error is omitted entirely and
+  the child errors are shown instead:
+  ```
+  line | field               | error
+  ---- | ------------------- | ----------------------------------------------
+  8    | Changes[0].ToArea.Y | Invalid type. Expected Integer but got String.
+  8    | Changes[0].ToArea   | Missing required fields: Height.
+  ```
+
+  The child errors themselves may be marked `$transparent`, etc. If an error has no child errors,
+  this override is ignored.
+
+  Validation errors for `then` blocks are transparent by default, unless overridden.
+
+</dd>
+</dl>
+
+### Using a schema file directly
+You can reference the validator schemas in your JSON file directly using the `$schema` field, for
+text editors that support schema validation. For example:
+```js
+{
+   "$schema": "https://smapi.io/schemas/manifest.json",
+   "Name": "Some mod",
+   ...
+}
+```
+
+Available schemas:
+
+format | schema URL
+------ | ----------
+[SMAPI `manifest.json`](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest) | https://smapi.io/schemas/manifest.json
+[Content Patcher `content.json`](https://github.com/Pathoschild/StardewMods/tree/develop/ContentPatcher#readme) | https://smapi.io/schemas/content-patcher.json
+
+## Web API
+### Overview
+SMAPI provides a web API at `api.smapi.io` for use by SMAPI and external tools. The URL includes a
+`{version}` token, which is the SMAPI version for backwards compatibility. This API is publicly
+accessible but not officially released; it may change at any time.
+
+### `/mods` endpoint
+The API has one `/mods` endpoint. This crossreferences the mod against a variety of sources (e.g.
+the wiki, Chucklefish, CurseForge, ModDrop, and Nexus) to provide metadata mainly intended for
+update checks.
+
+The API accepts a `POST` request with these fields:
+
+<table>
+<tr>
+<th>field</th>
+<th>summary</th>
+</tr>
+
+<tr>
+<td><code>mods</code></td>
+<td>
+
+The mods for which to fetch metadata. Included fields:
+
+
+field | summary
+----- | -------
+`id`  | The unique ID in the mod's `manifest.json`. This is used to crossreference with the wiki, and to index mods in the response. If it's unknown (e.g. you just have an update key), you can use a unique fake ID like `FAKE.Nexus.2400`.
+`updateKeys` | _(optional)_ [Update keys](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest#Update_checks) which specify the mod pages to check, in addition to any mod pages linked to the `ID`.
+`installedVersion` | _(optional)_ The installed version of the mod. If not specified, the API won't recommend an update.
+`isBroken` | _(optional)_ Whether SMAPI failed to load the installed version of the mod, e.g. due to incompatibility. If true, the web API will be more permissive when recommending updates (e.g. allowing a stable → prerelease update).
+
+</td>
+</tr>
+
+<tr>
+<td><code>apiVersion</code></td>
+<td>
+
+_(optional)_ The installed version of SMAPI. If not specified, the API won't recommend an update.
+
+</td>
+</tr>
+
+<tr>
+<td><code>gameVersion</code></td>
+<td>
+
+_(optional)_ The installed version of Stardew Valley. This may be used to select updates.
+
+</td>
+</tr>
+
+<tr>
+<td><code>platform</code></td>
+<td>
+
+_(optional)_ The player's OS (`Android`, `Linux`, `Mac`, or `Windows`). This may be used to select updates.
+
+</td>
+</tr>
+
+<tr>
+<td><code>includeExtendedMetadata</code></td>
+<td>
+
+_(optional)_ Whether to include extra metadata that's not needed for SMAPI update checks, but which
+may be useful to external tools.
+
+</td>
+</table>
+
+Example request:
+```js
+POST https://api.smapi.io/v3.0/mods
+{
+   "mods": [
+      {
+         "id": "Pathoschild.ContentPatcher",
+         "updateKeys": [ "nexus:1915" ],
+         "installedVersion": "1.9.2",
+         "isBroken": false
+      }
+   ],
+   "apiVersion": "3.0.0",
+   "gameVersion": "1.4.0",
+   "platform": "Windows",
+   "includeExtendedMetadata": true
+}
+```
+
+Response fields:
+
+<table>
+<tr>
+<th>field</th>
+<th>summary</th>
+</tr>
+
+<tr>
+<td><code>id</code></td>
+<td>
+
+The mod ID you specified in the request.
+
+</td>
+</tr>
+
+<tr>
+<td><code>suggestedUpdate</code></td>
+<td>
+
+The update version recommended by the web API, if any. This is based on some internal rules (e.g.
+it won't recommend a prerelease update if the player has a working stable version) and context
+(e.g. whether the player is in the game beta channel). Choosing an update version yourself isn't
+recommended, but you can set `includeExtendedMetadata: true` and check the `metadata` field if you
+really want to do that.
+
+</td>
+</tr>
+
+<tr>
+<td><code>errors</code></td>
+<td>
+
+Human-readable errors that occurred fetching the version info (e.g. if a mod page has an invalid
+version).
+
+</td>
+</tr>
+
+<tr>
+<td><code>metadata</code></td>
+<td>
+
+Extra metadata that's not needed for SMAPI update checks but which may be useful to external tools,
+if you set `includeExtendedMetadata: true` in the request. Included fields:
+
+field | summary
+----- | -------
+`id`  | The known `manifest.json` unique IDs for this mod defined on the wiki, if any. That includes historical versions of the mod.
+`name` | The normalised name for this mod based on the crossreferenced sites.
+`nexusID` | The mod ID on [Nexus Mods](https://www.nexusmods.com/stardewvalley/), if any.
+`chucklefishID` | The mod ID in the [Chucklefish mod repo](https://community.playstarbound.com/resources/categories/stardew-valley.22/), if any.
+`curseForgeID` | The mod project ID on [CurseForge](https://www.curseforge.com/stardewvalley), if any.
+`curseForgeKey` | The mod key on [CurseForge](https://www.curseforge.com/stardewvalley), if any. This is used in the mod page URL.
+`modDropID` | The mod ID on [ModDrop](https://www.moddrop.com/stardew-valley), if any.
+`gitHubRepo` | The GitHub repository containing the mod code, if any. Specified in the `Owner/Repo` form.
+`customSourceUrl` | The custom URL to the mod code, if any. This is used for mods which aren't stored in a GitHub repo.
+`customUrl` | The custom URL to the mod page, if any. This is used for mods which aren't stored on one of the standard mod sites covered by the ID fields.
+`main` | The primary mod version, if any. This depends on the mod site, but it's typically either the version of the mod itself or of its latest non-optional download.
+`optional` | The latest optional download version, if any.
+`unofficial` | The version of the unofficial update defined on the wiki for this mod, if any.
+`unofficialForBeta` | Equivalent to `unofficial`, but for beta versions of SMAPI or Stardew Valley.
+`hasBetaInfo` | Whether there's an ongoing Stardew Valley or SMAPI beta which may affect update checks.
+`compatibilityStatus` | The compatibility status for the mod for the stable version of the game, as defined on the wiki, if any. See [possible values](https://github.com/Pathoschild/SMAPI/blob/develop/src/SMAPI.Toolkit/Framework/Clients/Wiki/WikiCompatibilityStatus.cs).
+`compatibilitySummary` | The human-readable summary of the mod's compatibility in HTML format, if any.
+`brokeIn` | The SMAPI or Stardew Valley version that broke this mod, if any.
+`betaCompatibilityStatus`<br />`betaCompatibilitySummary`<br />`betaBrokeIn` | Equivalent to the preceding fields, but for beta versions of SMAPI or Stardew Valley.
+
+
+</td>
+</tr>
+</table>
+
+Example response with `includeExtendedMetadata: false`:
+```js
+[
+   {
+      "id": "Pathoschild.ContentPatcher",
+      "suggestedUpdate": {
+         "version": "1.10.0",
+         "url": "https://www.nexusmods.com/stardewvalley/mods/1915"
+      },
+      "errors": []
+   }
+]
+```
+
+Example response with `includeExtendedMetadata: true`:
+```js
+[
+   {
+      "id": "Pathoschild.ContentPatcher",
+      "suggestedUpdate": {
+         "version": "1.10.0",
+         "url": "https://www.nexusmods.com/stardewvalley/mods/1915"
+      },
+      "metadata": {
+         "id": [ "Pathoschild.ContentPatcher" ],
+         "name": "Content Patcher",
+         "nexusID": 1915,
+         "curseForgeID": 309243,
+         "curseForgeKey": "content-patcher",
+         "modDropID": 470174,
+         "gitHubRepo": "Pathoschild/StardewMods",
+         "main": {
+            "version": "1.10",
+            "url": "https://www.nexusmods.com/stardewvalley/mods/1915"
+         },
+         "hasBetaInfo": true,
+         "compatibilityStatus": "Ok",
+         "compatibilitySummary": "✓ use latest version."
+      },
+      "errors": []
+   }
+]
+```
+
+## Short URLs
+The SMAPI web services provides a few short URLs for convenience:
+
+short url | → | target page
+:-------- | - | :----------
+[smapi.io/3.0](https://smapi.io/3.0) | → | [stardewvalleywiki.com/Modding:Migrate_to_SMAPI_3.0](https://stardewvalleywiki.com/Modding:Migrate_to_SMAPI_3.0)
+[smapi.io/community](https://smapi.io/community) | → | [stardewvalleywiki.com/Modding:Community](https://stardewvalleywiki.com/Modding:Community)
+[smapi.io/docs](https://smapi.io/docs) | → | [stardewvalleywiki.com/Modding:Index](https://stardewvalleywiki.com/Modding:Index)
+[smapi.io/package](https://smapi.io/package) | → | [github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md](https://github.com/Pathoschild/SMAPI/blob/develop/docs/technical/mod-package.md)
+[smapi.io/troubleshoot](https://smapi.io/troubleshoot) | → | [stardewvalleywiki.com/Modding:Player_Guide/Troubleshooting](https://stardewvalleywiki.com/Modding:Player_Guide/Troubleshooting)
+[smapi.io/xnb](https://smapi.io/xnb) | → | [stardewvalleywiki.com/Modding:Using_XNB_mods](https://stardewvalleywiki.com/Modding:Using_XNB_mods)
+
+## For SMAPI developers
+### Local environment
+A local environment lets you run a complete copy of the web project (including cache database) on
+your machine, with no external dependencies aside from the actual mod sites.
+
+Initial setup:
+
+1. [Install MongoDB](https://docs.mongodb.com/manual/administration/install-community/) and add its
+   `bin` folder to the system PATH.
+2. Create a local folder for the MongoDB data (e.g. `C:\dev\smapi-cache`).
+3. Enter your credentials in the `appsettings.Development.json` file. You can leave the MongoDB
+   credentials as-is to use the default local instance; see the next section for the other settings.
+
+To launch the environment:
+1. Launch MongoDB from a terminal (change the data path if applicable):
+    ```sh
+    mongod --dbpath C:\dev\smapi-cache
+    ```
+2. Launch `SMAPI.Web` from Visual Studio to run a local version of the site.  
+    <small>(Local URLs will use HTTP instead of HTTPS, and subdomains will become routes, like
+    `log.smapi.io` &rarr; `localhost:59482/log`.)</small>
+
+### Production environment
+A production environment includes the web servers and cache database hosted online for public
+access. This section assumes you're creating a new production environment from scratch (not using
+the official live environment).
+
+Initial setup:
+
+1. Launch an empty MongoDB server (e.g. using [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)).
+2. Create an AWS Beanstalk .NET environment with these environment properties:
+
+   property name                   | description
+   ------------------------------- | -----------------
+   `LogParser:PastebinDevKey`      | The [Pastebin developer key](https://pastebin.com/api#1) used to authenticate with the Pastebin API.
+   `LogParser:PastebinUserKey`     | The [Pastebin user key](https://pastebin.com/api#8) used to authenticate with the Pastebin API. Can be left blank to post anonymously.
+   `LogParser:SectionUrl`          | The root URL of the log page, like `https://log.smapi.io/`.
+   `ModUpdateCheck:GitHubPassword` | The password with which to authenticate to GitHub when fetching release info.
+   `ModUpdateCheck:GitHubUsername` | The username with which to authenticate to GitHub when fetching release info.
+   `MongoDB:Host`                  | The hostname for the MongoDB instance.
+   `MongoDB:Username`              | The login username for the MongoDB instance.
+   `MongoDB:Password`              | The login password for the MongoDB instance.
+   `MongoDB:Database`              | The database name (e.g. `smapi` in production or `smapi-edge` in testing environments).
+
+To deploy updates:
+1. Deploy the web project using [AWS Toolkit for Visual Studio](https://aws.amazon.com/visualstudio/).
+2. If the MongoDB schema changed, delete the MongoDB database. (It'll be recreated automatically.)