TOML schema for configuration

[uncenter]

A schema for the various TOML configuration files that yazi uses would be great! Helpful for not just editing a configuration but also could be used to autogenerate tables or something on the docs.

Schemas can be added with the $schema to get editor completions:

"$schema" = 'https://example.org/schema.json'

Here is an example schema from the Starship prompt: https://starship.rs/config-schema.json.
Resources for making a schema:

• https://json-schema.org/learn/getting-started-step-by-step (writing a schema)
• https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md#how-to (adding a schema to JSON schema store)

I'll give this a go in a PR sometime this week but wanted to open this up for discussion and if anyone else has experience with this.

---

The help wanted label relates to auto-generating documentation in yazi-rs/schemas#7 if you want to help!

[sxyazi]

Nice to have!

[uncenter]

I have a few clarifying questions about the yazi.toml config:

• layout = [ 1, 4, 3 ] - From what I can tell it is an array of three integers, where each integer ranges from 0 or 1 to 8. My question is: is the lowest value 0 or 1? As in can it be 0/8 to hide the panel or something or is the lowest just 1/8.
• [preview] - For all of the numeric properties here, what are the constraints? What values can tab_size be, max_width, max_height?
• [tasks] - For all of the numeric properties here, what are the constraints? What values can micro_workers be, macro_workers, bizarre_retry?

I assume user configs are merged with the default one?

[uncenter]

I have a working draft of the schema - where should I put it for now?

[uncenter]

I mentioned generating docs from this earlier - I found this generator that can generate markdown files from a schema: https://github.com/coveooss/json-schema-for-humans. I think the output is pretty ugly but it is a good proof of concept. We could fork it maybe? I wouldn't suggest making one in Rust since there don't seem to be any good schema parsers or existing generators.

[sxyazi]

layout = [ 1, 4, 3 ] - From what I can tell it is an array of three integers, where each integer ranges from 0 or 1 to 8. My question is: is the lowest value 0 or 1? As in can it be 0/8 to hide the panel or something or is the lowest just 1/8.

Each element of that tuple has a u32 type, which means it ranges from 0 to 2^32-1, but the sum of them must be greater than 0.

[preview] - For all of the numeric properties here, what are the constraints? What values can tab_size be, max_width, max_height?

yazi/config/src/preview/preview.rs

Lines 11 to 13 in d04f8ac

	pub tab_size: u32,
	pub max_width: u32,
	pub max_height: u32,

[tasks] - For all of the numeric properties here, what are the constraints? What values can micro_workers be, macro_workers, bizarre_retry?

yazi/config/src/tasks/tasks.rs

Lines 8 to 13 in d04f8ac

	#[validate(range(min = 3, message = "Cannot be less than 3"))]
	pub micro_workers: u8,
	#[validate(range(min = 5, message = "Cannot be less than 5"))]
	pub macro_workers: u8,
	#[validate(range(min = 3, message = "Cannot be less than 3"))]
	pub bizarre_retry: u8,

I assume user configs are merged with the default one?

Yep and it's currently limited to the second level, see #51 (comment)

[sxyazi]

I have a working draft of the schema - where should I put it for now?

Maybe we can create a new repo in yazi-rs org?

[sxyazi]

I mentioned generating docs from this earlier - I found this generator that can generate markdown files from a schema: https://github.com/coveooss/json-schema-for-humans. I think the output is pretty ugly but it is a good proof of concept. We could fork it maybe? I wouldn't suggest making one in Rust since there don't seem to be any good schema parsers or existing generators.

Seems it doesn't support large sections of markdown content, I'm not quite sure how to integrate it into the existing docs, maybe we should keep them both?

[uncenter]

I have a working draft of the schema - where should I put it for now?

Maybe we can create a new repo in yazi-rs org?

That would be nice! We could also experiment with generating documentation there before we try it on the docs repo.

[uncenter]

I mentioned generating docs from this earlier - I found this generator that can generate markdown files from a schema: coveooss/json-schema-for-humans. I think the output is pretty ugly but it is a good proof of concept. We could fork it maybe? I wouldn't suggest making one in Rust since there don't seem to be any good schema parsers or existing generators.

Seems it doesn't support large sections of markdown content, I'm not quite sure how to integrate it into the existing docs, maybe we should keep them both?

I was thinking we could fork it and work with some custom templates to refine it closer to what we have now, just more precise/accurate.

[uncenter]

layout = [ 1, 4, 3 ] - From what I can tell it is an array of three integers, where each integer ranges from 0 or 1 to 8. My question is: is the lowest value 0 or 1? As in can it be 0/8 to hide the panel or something or is the lowest just 1/8.

Each element of that tuple has a u32 type, which means it ranges from 0 to 2^32-1, but the sum of them must be greater than 0.

[preview] - For all of the numeric properties here, what are the constraints? What values can tab_size be, max_width, max_height?

yazi/config/src/preview/preview.rs

Lines 11 to 13 in d04f8ac

	pub tab_size: u32,
	pub max_width: u32,
	pub max_height: u32,

[tasks] - For all of the numeric properties here, what are the constraints? What values can micro_workers be, macro_workers, bizarre_retry?

yazi/config/src/tasks/tasks.rs

Lines 8 to 13 in d04f8ac

	#[validate(range(min = 3, message = "Cannot be less than 3"))]
	pub micro_workers: u8,
	#[validate(range(min = 5, message = "Cannot be less than 5"))]
	pub macro_workers: u8,
	#[validate(range(min = 3, message = "Cannot be less than 3"))]
	pub bizarre_retry: u8,

I assume user configs are merged with the default one?

Yep and it's currently limited to the second level, see #51 (comment)

I'm not sure if it is worth specifying the maximum number because it is so high but I'll just put a minimum of zero for all of those.

[sxyazi]

That would be nice! We could also experiment with generating documentation there before we try it on the docs repo.

Done. https://github.com/yazi-rs/scheme

I was thinking we could fork it and work with some custom templates to refine it closer to what we have now, just more precise/accurate.

This will be great. I will complete the documentation for the theme system (and part of the plugin system) before Yazi v1.0.5. I'm still considering the layout, which largely depends on the content. It might happened before that.

I'm not sure if it is worth specifying the maximum number because it is so high but I'll just put a minimum of zero for all of those.

That's enough I think.

[uncenter]

That would be nice! We could also experiment with generating documentation there before we try it on the docs repo.

Done. yazi-rs/scheme

Thank you! This is a little picky but I think schema makes more sense than scheme (for the repo name)?

[sxyazi]

This is a little picky but I think schema makes more sense than scheme (for the repo name)?

Okay, done!

[uncenter]

Closed in #506.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days. ⏳ This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.