From 41f7e15b30967ebdbec0c03fa035de26ef85c394 Mon Sep 17 00:00:00 2001
From: Robert Jackson <me@rwjblue.com>
Date: Sat, 11 Jan 2025 21:40:16 -0500
Subject: [PATCH] docs: Expose config-schema.json in the docs site

When landed and published, this will expose the config file as:

https://jj-vcs.github.io/jj/latest/config-schema.json

Exposing the schema like that will allow users to reference in their
`~/.config/jj/config.toml` like:

```toml
"$schema" = 'https://jj-vcs.github.io/jj/latest/config-schema.json'
```

At which point any user with a configured LSP for TOML files will get
inline documentation, suggestions on valid keys, &c.
---
 CHANGELOG.md            |  8 ++++++++
 docs/config-schema.json |  1 +
 docs/config.md          | 40 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 120000 docs/config-schema.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b4847623e..2a677617e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -68,6 +68,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 * New template function `config(name)` to access to configuration variable from
   template.
 
+* Publish `config-schema.json` in the documentation site. Users can now reference
+  the schema in their `~/.config/jj/config.toml` file:
+
+```toml
+# Get editor completions based on the config schema
+"$schema" = "https://jj-vcs.github.io/jj/latest/config-schema.json"
+```
+
 ### Fixed bugs
 
 * Fixed diff selection by external tools with `jj split`/`commit -i FILESETS`.
diff --git a/docs/config-schema.json b/docs/config-schema.json
new file mode 120000
index 0000000000..a0b20323fc
--- /dev/null
+++ b/docs/config-schema.json
@@ -0,0 +1 @@
+../cli/src/config-schema.json
\ No newline at end of file
diff --git a/docs/config.md b/docs/config.md
index 00e6c20528..7c8b47fa6c 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -23,12 +23,17 @@ These are listed in the order they are loaded; the settings from earlier items
 in the list are overridden by the settings from later items if they disagree.
 Every type of config except for the built-in settings is optional.
 
+You can enable JSON Schema validation in your editor by adding a `$schema`
+reference at the top of your TOML config files. See [JSON Schema
+Support] for details.
+
 See the [TOML site] and the [syntax guide] for a detailed description of the
 syntax. We cover some of the basics below.
 
 [the user config file]: #user-config-file
 [TOML site]: https://toml.io/en/
 [syntax guide]: https://toml.io/en/v1.0.0
+[JSON Schema Support]: #json-schema-support
 
 The first thing to remember is that the value of a setting (the part to the
 right of the `=` sign) should be surrounded in quotes if it's a string.
@@ -1233,6 +1238,41 @@ default locations. For example,
 env JJ_CONFIG=/dev/null jj log       # Ignores any settings specified in the config file.
 ```
 
+### JSON Schema Support
+
+Many popular editors support TOML file syntax highlighting and validation. To
+enable schema validation in your editor, add this line at the top of your TOML
+config files:
+
+```toml
+"$schema" = "https://jj-vcs.github.io/jj/latest/config-schema.json"
+```
+
+This enables features like:
+
+- Autocomplete for config keys
+- Type checking of values
+- Documentation on hover
+- Validation of settings
+
+Here are some popular editors with TOML schema validation support:
+
+- VS Code
+  - Install [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
+
+- Neovim/Vim
+  - Use with [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) and [taplo](https://github.com/tamasfe/taplo)
+
+- JetBrains IDEs (IntelliJ, PyCharm, etc)
+  - Install [TOML](https://plugins.jetbrains.com/plugin/8195-toml) plugin
+
+- Sublime Text
+  - Install [LSP](https://packagecontrol.io/packages/LSP) and [LSP-taplo](https://packagecontrol.io/packages/LSP-taplo)
+
+- Emacs
+  - Install [lsp-mode](https://github.com/emacs-lsp/lsp-mode) and [toml-mode](https://github.com/dryman/toml-mode.el)
+  - Configure [taplo](https://github.com/tamasfe/taplo) as the LSP server
+
 ### Specifying config on the command-line
 
 You can use one or more `--config`/`--config-file` options on the command line