search

picocms / Pico

Pico is a stupidly simple, blazing fast, flat file CMS.
http://picocms.org/
MIT License
3.81k stars 616 forks source link

Issues with lots of themes installation #593

Closed gelavat closed 2 years ago

gelavat commented 3 years ago

I have tried several themes, and I encountered lot of issues with them.

Often, after installation, there is simply blank page displayed. Also, sometimes the documentation on how to modify texts and use the theme is not available at all and we have to guess things.

Examples of themes:

And that is the first ones I used so it is very disappointing. It is sad, because this doesn't seem to be a Pico CMS issue, only the theme providers issues. However this hurts Pico CMS as people try a few themes and after 30 minutes that it doesn't work the let Pico CMS down..

I suggest that all themes would be tested again, with latest Pico CMS version, from scratch with latest themes versions, and correct the mistakes that come up. Everything needs to be working out of the box, as people are new to Pico and don't know how to dig into each theme to fix them so it works. Installation instructions should be extremely clear and not complicated, telling what directory must be copied where, it is a pain to understand and figure this out, for all themes. Also instructions on how to modify pages contents should be available, else it is not worth publishing a theme that causes so much issues. Theme publishers should be contacted or else the theme should simply be removed.

That will certainly make Pico CMS much more attractive and usable for newcomers.

mayamcdougall commented 3 years ago

I've addressed much of this on https://github.com/picocms/Pico/issues/592, but, if there is a specific theme you really like, I'd be happy to help you get going with it.

Unfortunately, most of the themes are just not things that are ready to go out-of-the-box, and/or have limited documentation provided. Sometimes, a little technical know-how is needed to diagnose and correct issues you may encounter. We try to make Pico as user-friendly as we can, but we're a small team.

Many of these themes were contributed once, then not touched again. If we were to enforce stricter guidelines and/or remove themes that weren't 100% perfectly documented, we'd have very little remaining to show in our gallery.

While I agree that the current situation isn't ideal, the alternative of simply not having any themes isn't much better.

Pico's original intention was kind of that you'd just create your own theme and it would provide you the framework to turn your Markdown into a webpage.

While the themes gallery is a good showcase of what others have created, there will always be some amount of web development or administration left to the end user.

While we'd love to have more "Ready-to-go" options in our gallery (and this is something that may happen in the future, as I noted on https://github.com/picocms/Pico/issues/592), it's really up to the community. And just like our Pico team, our community is really kind of small.

PhrozenByte commented 3 years ago

As explained by @mayamcdougall, we're a very small team and we just don't have the time to officially support 3rd-party themes and to do quality assurance. In the end we have to decide whether we want a place for themes, or not. Pico is no one-click CMS (even though it actually is from a technical point of view, but that's kinda nitpicky :laughing:), it rather targets web developers which seek for a very simple, yet powerful alternative to create their own website. Thus we require some basic knowledge in the used technologies (like Markdown, YAML, Twig and web development in general, not necessarily PHP).

Most 3rd-party plugins and themes were made by people for their own websites, thus documentation never was their top priority - and here we are now. As explained by Maya, we can't just fix the issues with these themes, since we simply don't have permission to do so. Most issues are well known and have been reported to the developers already, but some of these projects are kinda abandoned. Just to make this clear, this is fine! All of this is open source, people are sacrificing their spare time, we simply have no entitlements here. We can only choose whether to include them in our list, or not. For now we have decided to rather include them, even though this is no final decision. More opinions are very welcome.

Without any question, this situation is suboptimal. Any help is very much appreciated @gelavat! :heart:

gelavat commented 3 years ago

Thanks both for your interesting explanations and inputs. I like Pico CMS a lot, It is incredibly powerful and just with flat files... amazing!

In my opinion removing completely the themes would not be an option. Pico CMS with the default theme is very ugly. It is ok as we know that we can install other themes, but without those themes it would not be usable nowadays, at least I wouldn't have used it. Also, with the themes that are currently available, the most beautiful ones are really nice once they work!

I am already in contact with some of those themes to improve the documentation on how to install and customize the content. E.g. https://github.com/unicate/pico-bulma/issues/3

These two parts are very important because Pico noobs like me really need it. We don't know the structure, the programming, etc... although now I start to get it more precisely, you have to see that newcomers are just willing to install Pico CMS and then quickly the best theme they find. And of course, as now it is very difficult to make many themes work, they will get stuck if they choose the bad one and not try further and simply stop using Pico. However usually there are just a few little things to correct and hence it seems that proper documentation will really make things done the right way. It doesn't need to be a full automatic installation, what is available now is very fine, we understand that it needs to be installed manually and this is ok.

So I would do those recommendations that could be very helpful: You could add a requirement for the themes providers that the installation and customization sections in their Readme.md file are the most accurate possible. They should test on a new directory their github content, following the Installation section of their readme.md file, and it must work out of the box with the pictures shown and everything like in their demo page, or very close to it. Also a customization section must exist, so that people know much quicker how to change the content as they need. With this, I am pretty sure that it will solve the issue completely. Of course, removing a theme if those sections are not working would be the last option, to be avoided, but at least they get the guidelines and are motivated to do it. That should be stated somewhere in your theme creation guidelines.

In parallel to this, I would recommend those things:

So this is enforcing things a bit but not too much, with quite a low overhead. I am sure it would help consistency, robustness and adoption of Pico CMS.

Thanks for that great tool!

PhrozenByte commented 3 years ago

Thank you very much for your input @gelavat :+1: We'll definitely take this into consideration, these are very good suggestions, but I'm afraid our time is too limited to actually make this happen. Maybe you wanna help us and undertake some responsibility here? Your help with reporting these issues to the respective developers and possibly also providing them with some suggestions on how they could improve their docs (you did struggle with them, so your input is way more helpful than ours could ever be) - possibly with a ready-to-merge pull request - is very welcome! :heart:

mayamcdougall commented 3 years ago

Pico CMS with the default theme is very ugly.

Don't let @PhrozenByte see that, lol. 🙈

But no, the default theme isn't meant to look like a modern, professional website. It's just a template you can use as a starting place for your own theme or to learn how Pico's theming works. It's simple on purpose. 😉

Anyway, the biggest hurdle with any of these ideas is time. @PhrozenByte and I both volunteer our time to keep Pico maintained, with anything programming-related being on @PhrozenByte (I'm actually not a PHP developer. 😅). I try to handle the community and website tasks that way he doesn't have to worry about them.

Your ideas are valid. I don't think we get enough theme submissions for it to be practical to implement a "Top Five" guideline though (or to spend the time organizing, making the criteria, documenting the guidelines, managing and maintaining the "top five" themes themselves, etc). We get a new theme every couple months at best.

But, I do plan to implement a "Ready to Go" tag or label in the not-too-distant future.

And if I had more time, I'd pump out a few more themes because I enjoy porting them. I'm not much of a designer myself, but there's a lot of free HTML themes out there. If you look, many of the more modern themes in the gallery will say "Ported by/Original by" in their description.

My most recent effort was porting Stellar from HTML5 UP. If you want an example of what a "Ready to Go" theme might look like, Stellar is what I have in mind.

Most of the others I've ported were done a couple years ago. With Stellar, I had a bit of programming experience under my belt, and as such, took a much more programatic approach to its functionality.

Where some of the older ports were as basic as "Customize the strings on your web page by filling out these YML properties", Stellar's port allows a deeper level of customization without ever touching the Twig template.

I don't have a demo site for Stellar, since it's just a port, but you can compare HTML5 UP's demo site with the site for my iOS app, CheriPom, which is what I ported it for.

(Also, @PhrozenByte, slight plug for my own work. I haven't shared it before now because it was never relevant to Pico, but I've totally been waiting for somewhere to work that in. 😅)

The documentation for Stellar is a bit long and hopefully covers everything you'd need to know. I haven't exactly had to follow it myself though, so there could always be some things I missed. If you'd like to try it out in your Pico adventures, I wouldn't mind hearing your feedback on what worked for you and what didn't. 😉

As I said, in the future I'd like to do more of these all-in-one style themes.

Hopefully it doesn't sound like I'm shooting down too many of your ideas here. I can't stress enough that they're not bad ideas, they just don't fit our current situation that well. We do appreciate the input though, and technically, we could probably use the extra kick to get motivated on some of this stuff again. 😂

gelavat commented 2 years ago

Hello @PhrozenByte . Thanks for your inputs.

Maybe you wanna help us and undertake some responsibility here? Well, maybe why not. I won't come often, just from time to time. But it could help. I provided already a PR for the clean-blog with installation instructions update and a customization section, as per your suggestion. It has been accepted and now I think it works out of the box, I am very happy.

I think this is the solution. Also in case the themes repo owners do not answer, I think that we could just fork them and provide the fork address, so we can continue to improve the doc at least, or even more the theme in itself. Whenever they want to update that to their base repo we can then switch back to their repo, what do you think? This would simply be a change in the repo address shown on the themes page. One would be the original and the other link would be the "current stable" version.

Personally I like the idea of the 4-5 best themes, that we would watch more thoroughly for compatibility (to avoid too much work, but providing a working set of templates to the user so he doesn't need to try and fail). Whenever an update is made on these 4-5 themes, we would check that it is still valid and the installation procedure is still working.

However I also like @mayamcdougall 's suggestion with the "Ready-to-go" tag. That is a good idea too, but it would mean a lot more of tests and validation as it could be for all themes the case, and it can be broken at any time by udpates.

Hence I think that both solutions would be good to implement and not of too much hard work. The hard work is a bit for the compatibility test and installation procedure update, but that's basically all, the rest is quite simple.

Instead of the "Ready-to-go" tag, that will not be valid anymore once there is an update to the theme potentially, or to pico, I would rather suggest to put this kind of tag: "Last verified: " and put the date of validation (there can be serveral ones, so not always dependent on the theme version or commit). It should always be only with the latest pico version so that it makes it clear. Also this is the configuration that newcomers will always have. This way the user knows that it has been verified at a certain point. He can also tell us or the repo maintainer that it doesn't seem to be valid anymore if he encounters issues.

What about all that?

To continue this way, I would suggest this: I will try to fix some other themes. Then you could do with Maya a selection of the ones you prefer and that we know works with the installation instructions. Then there should just be a highlight of those themes with like a green frame or so, and 10% bigger, with a "top and supported" tag on them on the themes page. That would basically be all there is to do.

gelavat commented 2 years ago

Thanks @mayamcdougall I get it. Great work for the stellar theme. I didn't try it but it seems very nice, congratulations for the porting! I think that an example website is important to have for all themes, else it is difficult for users to go for it without trying. Maybe I can provide some hosting of that theme, of course out of the box version only, I would have to see.

mayamcdougall commented 2 years ago

Well, the reason I didn't do a demo site was that there'd be no difference out-of-the-box to the original theme's demo site.

The changes are all on the backend, leveraging Pico to turn what was once a single static HTML template into a dynamically generated website.

I didn't design the theme, nor do I want to take the credit for its design. That's why I reference the original demo site (and of course the practical aspect of not having to host something that would be identical to the end user anyway).

Anyway, to clarify a little on the "Ready-to-go tag", what I mean is to have a Category of theme titled "Ready-to-go" that would be at the top of the gallery with the existing All, General Purpose, Single Page, Portfolio, and Blog-Style filter buttons.

In addition to this, I may add some kind of badge to the image or description of the theme. I'm leaning toward putting it in the description because I'd like to save the idea of an image badge (or border) for recommended/top themes (also, putting it in the description wouldn't actually require any changes to the existing site). Too many items overlaid on the thumbnail would feel cluttered, so I think one overlay at most (on select items only) would be the goal here.

As far as other style changes go... the Gallery itself is a bit difficult to work with. The gallery is run by it's own, self-contained javascript applet that makes a lot of realtime changes to the page DOM.

If I remember correctly, it was a real pain to style things without it looking broken. 🤔

Things like a green border might be easy enough, but I don't think making items bigger is happening (at least, without the whole gallery looking broken).

And we could technically make a "top row" of themes by simply capitalizing the .md files of the ones we want at the top. It's case-sensitive alphabetical. That's how I've got the Default theme at the top right now. 😂

Also, I originally had some reservations about putting any themes "on top" in the past because I didn't want the Gallery to be biased. This goes especially so for not wanting to provide preferential treatment to my own themes (which do tend to go the extra mile with documentation and try to provide a good user experience).

But, since adding the wiki themes to the site, it has felt a bit more cluttered. 🤔

(@PhrozenByte, I'm wondering if in the future we should consider dropping the current gallery in favor of something paginated. It's visually impressive (or at least, it used to be 😂), but I'm not sure if it's practical for such a large number of entries. I'll add this to my research list on top of finding a list-based replacement for plugins.)

I'm going to put in a little work on the gallery tonight and see if I can come up with changes that I like.

Oh, and just to spend at least a little addressing it... I personally don't like the idea of a "Last Verified" tag. It seems unnecessary, seems like extra work (something we're trying to cut down on, as we've discussed in our discussion about revising the themes and plugins submission process), and just not of much benefit to the end user.

Pico's implementation has been stable for a long time. In general, a theme that worked years ago still works today (even if their documentation might be lacking or outdated). Also, with most of the themes being untouched, there just aren't any changes to "verify" on either side (Pico's or the theme's).

Basically, I see it being something that would just fall to the wayside, and then end up looking bad. It'll look good to see Last Verified: <Last week's date> on a theme, but pretty soon that'll become Last Verified: <Last year's date>. And while neither Pico or the Theme has changed (significantly) in that time, without taking the extra effort to make sure nothing has broken, the date would just drift further into the past.

Idk, "Last Verified" doesn't sound like a lot of work at face value... but when you think about how a "Last Verified" date is only useful if it's recent, it starts to become a much bigger maintenance headache.

And again, that's just my opinion on the matter. And again like before, it's not a bad idea in general, I just don't feel like it fits our circumstance. 😕

PhrozenByte commented 2 years ago

Just wanna leave a :heart: here, I totally agree with everything that has been mentioned/suggested/noted here and I feel like that this discussion is going into the right direction! :+1:

(@PhrozenByte, I'm wondering if in the future we should consider dropping the current gallery in favor of something paginated. It's visually impressive (or at least, it used to be joy), but I'm not sure if it's practical for such a large number of entries. I'll add this to my research list on top of finding a list-based replacement for plugins.)

I agree. Feel free to replace it with something else, the website's source code (JS/CSS/HTML) is very clumsy in general. Maybe it's a good time to finally switch to Pico, too?

mayamcdougall commented 2 years ago

Maybe it's a good time to finally switch to Pico, too?

🤯*

(Head exploding emoji. I tend to use Apple devices for everything these days, so I legit have no idea what emoji character support looks like these days on Linux and Android. Let me know if I'm ever just posting a bunch of "missing character boxes" for you. 😂)

So, "Switching the website to Pico" sounds like it needs it's own Issue. Some things I'd be wondering would be:

If you want to make a new issue to discuss this, I can copy this comment over to it. Otherwise it can just be some things to keep in the back of our minds for later.

PhrozenByte commented 2 years ago

Switching to Pico basically means that we'd use Pico as a static website generator. We'd set up a GitHub Action that installs Pico on the CI server and creates a static copy of the website using wget -r. These static HTML pages will be commited to the picocms.github.io repo then. No hosting required. The CI scripts are no big deal at all, it's rather about switching from Liquid (Jekyll's template engine) to Twig.

About the theme: I don't really have any preference here. I doesn't look bad, I kinda like it, but it definitely needs improvement - both visually (the theme isn't mobile-ready in general, just take the font size) and from a technical point of view (the CSS/JS is very clumsy).

Yes, a new issue might be a good idea.

mayamcdougall commented 2 years ago

That sounds a little clunky, lol.

I've never done anything with CI stuff, so I'll take your word for it that it'd be a simple setup. 👍

I assume there'd be like a separate "statically generated" branch or something to hold the output files without contaminating the main site repo? (Kind of like the older days where the site was in the gh-pages branch on the main repo).

I'm torn on the theme as well. Honestly, I hate making big changes to it because it feels held together in places with "gum and paper clips". I also don't really like that it's essential a bunch of old leftover bits of a commercial theme. I'm sure we've got tons of extra cruft in there that isn't actually used by anything anymore (or never was).

Since moving to Pico would require a rewrite either way, I think I'd prefer to just port a new theme. Something with a similar layout and structure to the existing theme, that way as much of the site as possible could be a 1:1 reimplementation. Extras like the gallery could always be patched on top of whatever theme we choose (license permitting), or replaced with newer implementations.

With this route, we'd also have a fully open theme in the end that we could put in the theme gallery. It'd also be a bit of a flex to say "Not only does the site run Pico, here's the theme for your own usage." (Probably with a different default color scheme though, that way anyone else using it doesn't start with a carbon-copy of Pico's site, lol). 😉

mayamcdougall commented 2 years ago

Just closed this tab accidentally and lost a whole post. 🤦🏻‍♀️

Oh well, I should get more the the point for once.

Gallery is Isotope, licensed Commercial/GPLv3. We could use it as long as the new theme was GPLv3, not MIT.

Fancybox (the image viewer) used to be MIT and is now fully commercial. Not sure what version we use.

I'll probably be replacing these if we do a new theme.

\</comment> 😩

github-actions[bot] commented 2 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in two days if no further activity occurs. Thank you for your contributions! :+1: