-
Notifications
You must be signed in to change notification settings - Fork 62
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
How to add project with plugins collection? #140
Comments
Hi! It seems to fit in the Blogging category. Each project can have multiple plugins attached: - name: Publisher for MkDocs
mkdocs_plugin: [pub-meta, pub-blog, pub-obsidian, pub-social, pub-minifier, pub-debugger]
github_id: mkusz/mkdocs-publisher
pypi_id: mkdocs-publisher
labels: [plugin]
category: blogging |
It's probably also possible to create a few separate entries but specifying the same repository several times. We haven't tested if it actually works but we will surely have a precedent for that sooner or later. |
@pawamoy I only partly agree. Yes blogging is one of the main functionality of the project (initialy, the project was named My own idea was to do something like that:
The only problem I can see, is that (after @oprypin comment), in this approach, all plugins will contain the same description taken from git repo. Am I correct? |
Yes but for that it's possible to just set the The actual problems are:
|
I don't think we'll allow a plugin to be in several categories, need to pick one |
Kinda agree on the unfair advantage with the stars, but there is also an another side of the coin: so far all the plugins that are separate entities, don't have to think if they are compatible with any other plugins. This leads to dependency hell and maintenance problems where one project have to wait for potential issue fixes in another project/repo. Having all the plugins inside one project, we can try to minimalize those problems (the same approach can be seen in Material for MkDocs). Also, if we think about the unfair advantage this way, Material for MkDocs has the same problem since this is a theme with a few plugins (search and debug for sure).
Probably the other solution would be to create some sort of the meta (or plugin collections) category for projects like this. I don't fully agree with looking at this as a 6 separate project. It's rather 1 project with 6 plugins that can be used in separation but works best in cooperation (just like Material for MkDocs that is a theme with search plugin that expands theme). Project has some goals and PS. If you can see this as a single project, there is no problem with unfair adventages ;) |
We mostly agree, but just this part stood out as strange to me:
If it's a single project then it can go to a single category 🤔 |
Yes, but which one is the correct one? I don't feel like blogging is the correct one. The only one that now seems the best fit (kinda) is |
Material for MkDocs is not a plain theme anymore. It started as a theme 7.5 years ago, but has become a documentation framework built on top of MkDocs. We plan to add the 12 plugins that we bundle which also work with other themes (in fact, all of them) into the separate categories of the catalog as well. |
@squidfunk are you going to separate them into multiple repositories? Asking because (according to above discussion) it's not possible (or at least not desirable) at the current stage of this catalog. |
I talked to the maintainers of this repository and was told that it is perfectly possible to list the project multiple times in separate categories, only listing the respective plugin that applies to the given category. |
I will follow that path and make a PR with a plugin categorization described in one of my previous comments. |
If we go this route, I think we should remove the total stars count from the first paragraph in the README, unless best-of-generator deduplicates the info correctly of course. If it doesn't, the 12 Material for MkDocs plugins will blow up the count to something like 200k+ stars instead of 30k 😅 Feel free to send PRs anyway and we'll see how it behaves. |
Couldn't you deduplicate total stars by grouping by Lines 64 to 70 in b88c86a
|
Everything is possible, it's just that we didn't write the code of the best-of-generator, so this would take time. |
There is some code in |
Thanks. That lead me to read the docs again, and there are interesting bits:
I don't think groups would apply to Material for MkDocs or Publisher for MkDocs though, since their different plugins are in different categories. Also it's possible to override the star count of a project with |
Seems like |
The script you mention only checks the correctness/completeness of the metadata, it does not generate the contents of the README. Any custom logic for the Markdown contents generation must happen in the best-of-generator code EDIT: Maybe you meant to add a warning for duplicated projects that do not set |
By the way, I forgot that @oprypin had forked the generator here: https://github.com/mkdocs/best-of-generator. So at least reviews, merges and releases can happen fast. |
Didn't think about this, but it could be sufficient (+ add as a check before merge). The only thing that I wonder is how it will affect project position inside a category? |
By the way, in the meantime, this plugin hasn't been added to the catalog in any capacity, so we're missing it |
Thanks for the reminder. I'll unblock some time tomorrow to try working on this. |
I will add my plugins today in the evening. Sorry for the delay. |
I'm running some experiments. Here's some feedback:
Footnotes
|
Also, other metrics are taken into account when calculating the score: forks count, contributors count, etc., which should all be divided the same way as stars... Might be cumbersome to implement but I'll try. Let me know what you think, there might be better ways I didn't think of. Maybe we could simply get rid of the whole score calculation and simply order projects alphabetically. |
The only reason for trying to have many stars/contributors/etc. is for the project to jump out of the category of project with less than 20 (this is the limit if I remember correctly) stars because when your project/plugin has less than that, it lands in this folded category and because of this it's less visible and harder to find. |
So your recommendation would be to leave the ranking as it is (without dividing stars and whatever), and just get rid of the "collapsed" feature (never hiding any project)? I'd be fine with that 🙂 |
Yes. |
I removed the total star count, as well as display restrictions (min description, min stars, min rank, homepage), and fixed metadata of a few projects. README updated, ready to accept PRs splitting monorepos across several categories 🙂 |
Hmm there are still 3 occurrences of hidden projects, I'll investigate. |
I will work on adding my project to the catalog, so we can see how it goes. Will mention this task in PR message so we will have some trace for future projects. |
Hi,
I'm the author of mkdocs-publisher project that contains multiple plugins. Some of them can be used separately, but some of them can work in cooperation. It's easier to test and maintain, especially when all of them are related to the one goal or personal web page/blog publishing. I want to add this project to this repository, but I'm not sure how to do it "the right way". Adding it as a
mkdosc-publisher
makes no sense, since there is no proper category for it. The close one is templates, since templates can contain multiple plugins, but it's not a template. The other idea is to add each of the plugins separately, but then I have to link all of them to the same repository, etc. If this is "the way" should I create a separate pull request or do a single one (it's described to do a one per plugin, but since it's a collection, should the same rule apply?). Please advise.The text was updated successfully, but these errors were encountered: