Thanks for moving this PR over here. I just thought we should try to avoid having multiple discussions/issues/PRs across different repos, and simply have everything in one place. Having this PR here does not mean that we are intending to move forward with this plan though, FYI.

Hmm I'm not sure this is the ideal format for flavors - mandating that flavors have to have preview images, READMEs, very specific file names, etc (https://yazi-rs.github.io/docs/flavors/overview/). This PR means this repository would have eight license files and five READMEs. This also doesn't solve the issue of duplicate tmtheme files, and the preview images should be in WebP instead of PNG.

mandating that flavors have to have preview images, READMEs, very specific file names, etc (https://yazi-rs.github.io/docs/flavors/overview/).

Each flavor is designed as a package that can be used and updated independently. It's necessary to provide separate READMEs and screenshots for them. I'm not sure where these files should be stored if not like this PR's structure:

~/.config/yazi/flavors/
├── catppuccin-frappe.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   ├── README.md
│   ├── screenshot.png
│   ├── LICENSE
│   └── LICENSE-tmtheme
├── catppuccin-mocha.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   ├── README.md
│   ├── screenshot.png
│   ├── LICENSE
│   └── LICENSE-tmtheme

This PR means this repository would have eight license files and five READMEs.

If we want to avoid duplicating README and LICENSE files, the only solution I can think of is to move them out of the flavor packages to the parent directory, resulting in the following structure:

~/.config/yazi/flavors/
├── catppuccin-frappe.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   └── screenshot.png
├── catppuccin-mocha.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   └── screenshot.png
├── README.md
├── LICENSE
└── LICENSE-tmtheme

The README and LICENSE for catppuccin appear in the ~/.config/yazi/flavors/ directory, which is strange as this directory should not contain anything that is not a flavor.

Also if a user only installs catppuccin-frappe.yazi without copying all those files, they won't have the README and LICENSE files, which means they'll lose the introduction and licensing information. And README, especially LICENSE, should not change so frequently, I don't see any harm in simply repeating them.

This also doesn't solve the issue of duplicate tmtheme files

About the duplicate tmtheme files, I understand that this will add more work, the solution is for me to maintain and take on this extra work myself - I have stated in this PR that I am willing to become the maintainer of this repo and maintain it.

and the preview images should be in WebP instead of PNG.

As for using PNG instead of WebP, this is also for the convenience of flavor users/creators. All the screenshot software I have installed (CleanShot X/Shottr) does not support outputting in WebP format. When someone wants to create a flavor for Yazi, they would have to figure out a way (perhaps through online tools or specialized software to convert image formats), this is an additional step.

AFAIK, some desktop environments/file managers also do not support WebP. For example, Thunar cannot preview it, but it does support PNG (I know there are definitely ways to support it by installing software, but this is just inconvenient IMO):

And even GitHub does not support it (I know you can write a user script to replace it with an img tag, also inconvenient):

PNG is a very old and mature format, and I haven't heard of any desktop environments that don't support it. I don't want to waste time chasing after new formats like AVIF and JPEG XL, which offer better compression ratios than WebP.

mandating that flavors have to have preview images, READMEs, very specific file names, etc (yazi-rs.github.io/docs/flavors/overview).

Each flavor is designed as a package that can be used and updated independently. It's necessary to provide separate READMEs and screenshots for them. I'm not sure where these files should be stored if not like this PR's structure:

~/.config/yazi/flavors/
├── catppuccin-frappe.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   ├── README.md
│   ├── screenshot.png
│   ├── LICENSE
│   └── LICENSE-tmtheme
├── catppuccin-mocha.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   ├── README.md
│   ├── screenshot.png
│   ├── LICENSE
│   └── LICENSE-tmtheme

This PR means this repository would have eight license files and five READMEs.

If we want to avoid duplicating README and LICENSE files, the only solution I can think of is to move them out of the flavor packages to the parent directory, resulting in the following structure:

~/.config/yazi/flavors/
├── catppuccin-frappe.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   └── screenshot.png
├── catppuccin-mocha.yazi/
│   ├── flavor.toml
│   ├── tmtheme.xml
│   └── screenshot.png
├── README.md
├── LICENSE
└── LICENSE-tmtheme

The README and LICENSE for catppuccin appear in the ~/.config/yazi/flavors/ directory, which is strange as this directory should not contain anything that is not a flavor.

Also if a user only installs catppuccin-frappe.yazi without copying all those files, they won't have the README and LICENSE files, which means they'll lose the introduction and licensing information. And README, especially LICENSE, should not change so frequently, I don't see any harm in simply repeating them.

A lot of this boils down to: I don't understand why your flavor specification mandates the locations, filenames, and general existence of files unrelated to the core operation as they relate to Yazi. Why does Yazi care as a program where a license or a README file is located? That shouldn't be in the specification in my opinion, its totally opinionated.

This also doesn't solve the issue of duplicate tmtheme files

About the duplicate tmtheme files, I understand that this will add more work, the solution is for me to maintain and take on this extra work myself - I have stated in this PR that I am willing to become the maintainer of this repo and maintain it.

It isn't about the amount of "work". It has been previously stated before that the tmtheme files aren't often updated over at catppuccin/bat anyways, but it is more about the principle of duplication and disorganization that we are trying to not break. Having users go download a separate file is not unheard of and isn't really much of a hassle.

and the preview images should be in WebP instead of PNG.

As for using PNG instead of WebP, this is also for the convenience of flavor users/creators. All the screenshot software I have installed (CleanShot X/Shottr) does not support outputting in WebP format. When someone wants to create a flavor for Yazi, they would have to figure out a way (perhaps through online tools or specialized software to convert image formats), this is an additional step.

Again, this boils down to: why is the flavor spec mandating this? It is literally nothing to do with Yazi lol. Catppuccin prefers to use WebP and I'm not sure why we can't. The only time a user will ever look at a preview image is in the README, before deciding if they want to use it.

AFAIK, some desktop environments/file managers also do not support WebP. For example, Thunar cannot preview it, but it does support PNG (I know there are definitely ways to support it by installing software, but this is just inconvenient IMO):

I'm not sure in what scenario a user would need to or want to have the preview images on their machines?

And even GitHub does not support it (I know you can write a user script to replace it with an img tag, also inconvenient):

GitHub displays WebP just fine in READMEs, which is the only place they are actually needed/used.

PNG is a very old and mature format, and I haven't heard of any desktop environments that don't support it. I don't want to waste time chasing after new formats like AVIF and JPEG XL, which offer better compression ratios than WebP.

Exactly. It isn't your job to police what image formats or file names people use for flavors ahah.

A lot of this boils down to: I don't understand why your flavor specification mandates the locations, filenames, and general existence of files unrelated to the core operation as they relate to Yazi. Why does Yazi care as a program where a license or a README file is located? That shouldn't be in the specification in my opinion, its totally opinionated.
Again, this boils down to: why is the flavor spec mandating this? It is literally nothing to do with Yazi lol. Catppuccin prefers to use WebP and I'm not sure why we can't. The only time a user will ever look at a preview image is in the README, before deciding if they want to use it.

I think the reason is simple, because it is what users need, and Yazi has always prioritized user experience as its primary goal.

As I mentioned above, each flavor is a separate package, so it needs its own README.md, screenshot.png, LICENSE, and LICENSE-tmtheme files:

• README.md: I'm not sure how users would know how to install and use it without a README, and it is also a best practice.
• screenshot.png: Users want to know what the flavor looks like, so it is necessary to provide a screenshot. If you don't, users will request you to add it, see Preview images add? yazi-rs/flavors#2 and Theme preview ; suggestion yazi-rs/flavors#4.
• LICENSE, LICENSE-tmtheme: Yazi values copyright, because flavors contain the necessary tmtheme.xml files, so adding the corresponding original author's LICENSE-tmtheme is a basic respect for their minimum labor achievements; similarly, if someone creates a flavor, including the author's LICENSE, it is also the most basic respect. If these files are missing in the flavor, such as moving these files to the parent directory to avoid duplication, it is a bug in the entire flavor specification that we need to try our best to avoid.

They need to be added eventually, so why not specify them in a unified and standardized way? This kind of determinism, such as the description file being called README.md, not README.txt, readme.md, ReadMe, etc., not only benefits users but also benefits Yazi maintainers (me). Such as the Yazi theme manager planned in the future, by using deterministic README.md, its content can be directly displayed without relying on constantly guessing different names, which is something I have been continuously advocating for to make future automation possible.

This is still the issue of convenience and automation that I keep mentioning. If catppuccin can't accept files containing tmtheme, I will close this PR because it no longer makes sense.

I'm not sure in what scenario a user would need to or want to have the preview images on their machines?
GitHub displays WebP just fine in READMEs, which is the only place they are actually needed/used.
Exactly. It isn't your job to police what image formats or file names people use for flavors ahah.

When users download and install multiple flavors and want to switch between them, what should they do? Is it to require them to constantly modify Yazi's configuration and then restart Yazi to see the effect?

Yazi's goal is to provide a consistent user experience for all users, and PNG is the way to achieve it - it seems that there are no devices that do not support PNG but support webp.

As a user of catppuccin

I definitely understand the concerns of @uncenter here. This way of handling themes in an application seems to be much more verbose and opinionated compared to most other CLI apps and how they handle themes.

It isn't about the amount of "work".

If a theme maintainer does not want to do the port due to effort then that is fine, any sane user of catppuccin should respect the free time put into maintaining this, but @uncenter you suggest that it isn't about the work needed. I believe once an app decides on a system of how themes are handled, then if a theme maintainer wants to claim they support it, I believe it should be done to the spec outlined by the app.

Otherwise catppuccin users would have to jump through hoops to implement the theme properly, which is the biggest reason I personally use catppuccin -- for everything I use in my dev environment catppuccin is supported and plug-and-play.

It has been previously stated before that the tmtheme files aren't often updated over at catppuccin/bat anyways

If a catppuccin/<port> requies a tmTheme, then I would hope that the port's repo has that file. It is unfortunate to need to go to the bat port for a tmTheme. You may disagree with me, but I feel each port should be able to stand on it's own and readily provide all files needed for the app its being ported to.

I will post a comment on "As a user of yazi" perspective too

As a user of yazi

Yazi values copyright, because flavors contain the necessary tmtheme.xml files, so adding the corresponding original author's LICENSE-tmtheme is a basic respect for their minimum labor achievements

Imagine any standard user of yazi who doesn't care much about Licensing, they want it to be as easy as possible: If there isn't an up to date port, but they still find the yazi theme toml file and a tmTheme, then they have to make blank or copy-pasted placeholder files for the other required files -- again making the user jump through hoops for a theme. @sxyazi I understand your principals on respecting copyright, and I appreciate the sentiment, but I can't see it being enforced in any meaningful way here.

Really it's the job of lawyers, and the due diligence of theme maintainers, to make sure copyright isn't infringed, if the themes are not developed by yazi then it shouldn't be yazi's responsibility. Having the flavor system be very opinionated on this, causes more friction for all maintainers of themes and all users of yazi, even in the event that all maintainers and users are already respecting copyright and licensing.

I partially understand your other points for why you want a theme to contain the files you outlined, but I must agree with @uncenter on:

why is the flavor spec mandating this? It is literally nothing to do with Yazi

It is up to the creators and maintainers of a theme to market and present their theme so that users want to use it, if they provide no screenshots or description then that's on them.

The only case in which I see this new flavor feature being useful, is if you are legitimately planning to implement a dashboard on yazi's website that users can search through with previews and details of themes (even in this scenario it isn't yazi's responsibility to enforce the flavor's license requirements, Microsoft's VS Code doesn't even require this).

But other than that I don't see a reason why yazi should require anything more than a toml with an optional tmTheme, especially since anyone can just circumvent the other required files by making garbage or empty files. Even if you were going to make a dashboard, you can opt to exclude any repo that doesn't have a screenshot, readme or license -- outright requiring these files to exist for a theme to even work on my own machine is still overreaching and too opinionated I think.

Reply to the part about Yazi

Imagine any standard user of yazi who doesn't care much about Licensing, they want it to be as easy as possible: If there isn't an up to date port, but they still find the yazi theme toml file and a tmTheme, then they have to make blank or copy-pasted placeholder files for the other required files

Are you referring to the old theme.toml? If so, theme.toml and flavor.toml are not designed to be simply swapped out.

The license is provided by the flavor author; it's their work. The design of flavors aims to prevent users from modifying them (which would cause update conflicts), so users shouldn't manually add a license.

If the flavor author uses the official flavor template (which is what we encourage), it already includes a blank license file and instructs in the README to replace it with their own. The situation you mentioned would only occur if the flavor author manually deletes it or doesn't use the official template.

Really it's the job of lawyers, and the due diligence of theme maintainers, to make sure copyright isn't infringed, if the themes are not developed by yazi then it shouldn't be yazi's responsibility. Having the flavor system be very opinionated on this, causes more friction for all maintainers of themes and all users of yazi, even in the event that all maintainers and users are already respecting copyright and licensing.

I've never thought that being opinionated is a bad thing. In fact, Yazi is full of opinions. It was originally developed to meet my personal needs and designed around my workflow (I was looking for an alternative to ranger/joshuto at the time), and I'm glad to see that many people also like it.

The debate about copyrights has never stopped, I'm not a lawyer, but this is my choice and stance because I truly haven't seen the harm and trouble adding a license would bring. It only brings benefits and makes the flavor a more robust project, which benefits the flavor author as well. They don't have to worry about whether they should/can include a license, what filename to use, etc. All of this is based on convention and best practices from experience.

It is up to the creators and maintainers of a theme to market and present their theme so that users want to use it, if they provide no screenshots or description then that's on them.

The reality is, it's difficult for flavor authors to promote their flavors, especially for niche software like Yazi, which has a limited audience. As a maintainer, I try my best to help promote them, including creating a separate resource page and a flavors repository, linking them in GitHub issues/discussions, and posting them in Yazi's Discord group.

The only case in which I see this new flavor feature being useful, is if you are legitimately planning to implement a dashboard on yazi's website that users can search through with previews and details of themes (even in this scenario it isn't yazi's responsibility to enforce the flavor's license requirements, Microsoft's VS Code doesn't even require this).

This seems to be what's currently being done at https://github.com/yazi-rs/flavors, flavor authors can create a PR to add their flavors to this repository, and I'll also add them when I discover new flavors, and it includes links and screenshots for each flavor, I can't imagine what it would be like without images; as I mentioned earlier, users will request you to add images.

I don't think comparing Yazi to VS Code is reasonable. The user base and plugins/flavors for Yazi are different, which limits the number of plugins/flavors. This allows me to directly submit a PR when I discover errors or areas for improvement - I've already contributed to many of them. My point is, we will ultimately lean towards being a small, exquisite, and close-knit community rather than a large, comprehensive one. Therefore, I don't think adding images is a big issue. If the flavor author forgets to add it, I or someone can even submit a PR for it directly. Of course, all of this is done with the author's approval; they have 100% right to reject the PR because it's their own repository.

But other than that I don't see a reason why yazi should require anything more than a toml with an optional tmTheme, especially since anyone can just circumvent the other required files by making garbage or empty files. Even if you were going to make a dashboard, you can opt to exclude any repo that doesn't have a screenshot, readme or license -- outright requiring these files to exist for a theme to even work on my own machine is still overreaching and too opinionated I think.

If you are using the new flavor, tmTheme is required, for reasons at catppuccin/catppuccin#2278 (comment) and catppuccin/catppuccin#2278 (comment).

The license is provided by the flavor author; it's their work. The design of flavors aims to prevent users from modifying them (which would cause update conflicts), so users shouldn't manually add a license.

The design is a good design I believe, but if someone wants to make their own theme without ever publishing it, then I can't imagine them creating any meaningful readme, license or screenshot -- it's trivial to do, but it's pointless clutter for them. The same might happen for when their favourite theme doesn't haven't a port on yazi, they want to port it, but for their own personal reasons don't want to publish the yazi port.

The debate about copyrights has never stopped, I'm not a lawyer, but this is my choice and stance because I truly haven't seen the harm and trouble adding a license would bring. It only brings benefits and makes the flavor a more robust project, which benefits the flavor author as well. They don't have to worry about whether they should/can include a license, what filename to use, etc. All of this is based on convention and best practices from experience.

This is a good argument for how the flavor spec is beneficial, especially for people making a theme from scratch on yazi. My point of view is coming more from the perspective of well established themes, take https://github.com/EdenEast/nightfox.nvim for example: They currently have 7 palettes and their workflow for making ports revolves around having a single template file (list of their templates here) that generates the theme for each port and all palettes. I'm sure they're not the only theme maintainers with a workflow like this.

For creating a theme from scratch, the flavor template is very good, for established themes like nightfox it now requires a complete refactor on how they generate ports if they want to officially support a yazi theme based on your flavor spec.

So my main concern is that enforcing this flavor spec may result in less ports being published for yazi, but it seems yazi still work with a flavor that only has a flavor.toml and tmTheme.xml file in its directory, if it remains that way I don't see any problem. And I want to clarify that I like yazi having a flavor template with established file names and best practices, you have made a good design for this. I just wouldn't like for 'best practices' to become 'required practices', because it may be the best for some people but a burden for others (especially for a theme like nightfox).

but if someone wants to make their own theme without ever publishing it, then I can't imagine them creating any meaningful readme, license or screenshot

If a user wants to create a theme for their own use, they should use theme.toml instead of flavor.toml, as described in the flavor specification:

The "flavor" is a pre-made Yazi theme, while what we typically refer to as a "theme" is the user's own theme, i.e. ~/.config/yazi/theme.toml file.

The purpose of flavor is to provide convenience for others to use. I'm not sure why one would use the flavor format if they just want to use it for themselves.

They currently have 7 palettes and their workflow for making ports revolves around having a single template file (list of their templates here) that generates the theme for each port and all palettes

I think Yazi relies on both flavor.toml and tmtheme.xml already breaking this, which means it can't be provided as a single file but must be a directory (package). I haven't used nightfox, but if nightfox accepts adding additional tmtheme.xml files, I don't think adding a license would be a problem either.

If nightfox considers this a burden, they can refuse to provide a flavor for Yazi and allow for some community integration, as long as their color scheme is public. There are already some examples of this in https://github.com/yazi-rs/flavors, such as onedark and tokyo-night maintained by community users. We could even maintain it as an official flavor if there is a demand for nightfox but no one is making it.

The same applies to Catppuccin, if Catppuccin cannot accept additional tmtheme and license files and sees this as a burden, I can completely understand. I just hope to see Yazi's flavor come in Catppuccin, as this would be beneficial for both Catppuccin and Yazi users.

If a user wants to create a theme for their own use, they should use theme.toml instead of flavor.toml, as described in the flavor specification

The purpose of flavor is to provide convenience for others to use. I'm not sure why one would use the flavor format if they just want to use it for themselves.

Oh! I keep forgetting that theme.toml isn't deprecated, so since that is staying as a feature for yazi then most of my concerns are resolved.

I think Yazi relies on both flavor.toml and tmtheme.xml already breaking this, which means it can't be provided as a single file but must be a directory (package). I haven't used nightfox, but if nightfox accepts adding additional tmtheme.xml files, I don't think adding a license would be a problem either.

That's true. So I'm not suggesting a change to the flavor spec, I think the new flavor approach is better and more convenient for users given that flavor.toml and tmTheme.xml must be provided, it reduces the need for users to hunt for both files individually, makes sense that the files are together for a yazi theme.

While the flavor spec is opinionated, there is still the free choice to support the original theme.toml implementation, so I don't think there is any problem here.

What I am imagining in the future is a community maintained dashboard such as https://vimcolorschemes.com/, which is how I discovered catppuccin and nightfox originally. There may be many users in the future that get introduced to various themes by exploring themes for yazi, and the new flavor spec enables a consistent and predictable way for themes to be presented through dashboards, centralised repos, or in chat rooms like discord. So users can browse and preview themes quickly, and theme maintainers are given a platform to present their theme, seems like a win-win.

Because of these reasons I think it would be a good idea for catppuccin to accept this PR once it is finalised.

OK, I'll finish up the remaining work on this PR in the next few days, then see if @sgoudham is interested in merging it, or just closing it, either is fine to me

Looks like the discussion may have stalled since the last post was 3 weeks ago. I spent an hour reading through this discussion, trying to identify what the pain points are. Here are the things that I gathered, and my suggestions for solutions:

Problem 1: no agreement on the format of preview images (webp vs. png)

I don't have a stance on which is better, but here is how this could be resolved:

• store the previews as one format in this repository, and convert to the other format in a build step. I think something like convert image.webp image.png (imagemagick) might suffice. This can be done in this repository, or in the future yazi theme site that @sxyazi mentioned there are plans for.
• or, have continuous integration do the conversion

Problem 2: many copies of license and readme files

I cloned this PR and it looks like the license and readme files are almost exact copies with minor changes. It seems that this can easily be solved by automation:

• copy the licenses over when building
• create the flavor readme files from a template
• the future yazi theme site could also do this
• or, just make the theme site reject any invalid flavors and some improvements can be made at that point when things are clearer
• or, the theme site can simply fall back to a top level readme as per some specification
• or, store the license files as symlinks in the repository

Let me know if I have missed some issues. As a user of yazi, I'm looking for a way to have my yazi plugins and themes (want to eventually use flavors) be tracked via git and some plugin manager so that I can pull in new features and fixes for them.

I can also provide this as a PR to address today's problems, and then the design can be improved on in the future.

I guess if I had to summarize the discussion, it is less so about the implementation details here and feasibility of the changes and moreso about the implementation of Yazi's flavor spec itself. As someone who has worked with Yazi since October of last year, created the schema files for the configuration spec, contributed heavily to the documentation, etc. I have some major issues with the flavor spec as is. Notably, as I've already said, I don't see why Yazi needs to mandate the filenames and presence of files not directly related to Yazi. I understand if the spec requires the tmtheme and the theme.toml files with certain names, but the rest - no. I think the best course of action is for me to open an RFC issue on the Yazi repository to move further discussion over there.

Ah I completely forgot about this PR - I'll finish the rest of this PR now

As there are no plans to improve the flavor spec, I don't think proceeding with this makes sense.

@uncenter would you accept a PR for the "minimal" spec you proposed?

It would allow me to proceed with my own config changes, would break no existing functionality, and could be improved on later in case agreement on the flavor spec can be reached.

for the "minimal" spec you proposed?

Uhhh sure... not sure how that solves your issue though. It wouldn't be a valid "flavor" (-_-) and it wouldn't work as a theme file.

in case agreement on the flavor spec can be reached.

My issue was closed without the slightest indication of any possibility of the spec changing. No discussion even! Not looking too good on that front. All my suggestions have been repeatedly rejected - removing those requirements, allowing a configuration option for a path to a theme file (remote and local), etc...

My issue was closed without the slightest indication of any possibility of the spec changing. No discussion even!

This is because I don't see the point of that issue - everything described in that issue is a repetition of the comments on this PR, and I've already provided explanations for them (GitHub/Discord). I really don't want to spend time discussing them all over again.

Of course, if there's any new content that hasn't been discussed before, feel free to file a new issue!