Skip to content

Commit

Permalink
docs: Expose config-schema.json in the docs site
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
rwjblue committed Jan 12, 2025
1 parent f1e91cd commit 41f7e15
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 0 deletions.
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
1 change: 1 addition & 0 deletions docs/config-schema.json
40 changes: 40 additions & 0 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 41f7e15

Please sign in to comment.