ShinyCMS

Today I merged PR #661 - Did Somebody Say Documentation?

The highlights of this PR are:

• Each major feature and each plugin now has its own Markdown documentation file in the /docs folder
• The new ShinyCMS documentation website is generated from the files in /docs, using MkDocs

The docs website is hosted on GitHub Pages, which is pretty straightforward to set up and keep updated with MkDocs. When I run 'mkdocs build' MkDocs generates a HTML version of each of my Markdown docs (applying my chosen theme at the same time), and puts them all in the /site directory. When I run 'mkdocs gh-deploy' it pushes the contents of that directory to the special gh-pages branch that GitHub Pages serves the site from.

The only fiddly bit was preventing CircleCI from trying to run my tests on that gh-pages branch, as they would fail spectacularly on account of it having no actual code in it. The solution I went for in the end was to put a minimal 'do nothing' CircleCI config in /site; MkDocs kindly leaves this in place when I run 'mkdocs build', and then pushes it up along with the rest when I run 'mkdocs gh-deploy'.

I got a Google alert today letting me know that GitHub had automatically created this page encouraging people, especially less experienced people, to get involved with the ShinyCMS-ruby project - triggered by my tagging a few issues as 'good first issue'.

This made me wonder if there was anything I could do to further help and encourage anybody who's thinking about picking up one of those issues, but maybe isn't quite confident in doing so. I've always admired the way the Dreamwidth project brings new people into open source development and gives them a really positive start - I don't imagine I'll be getting quite as much interest as them :-p but I'd like to do whatever I can if anybody out there is interested. I was helped by the community on freenode a huge amount when I started out many years ago and I'm always looking for ways to pay that forward! In my day job I spent most of the last four years leading a team of 6-8 developers, and one of my favourite things about that role has been mentoring people who are just starting out in their careers. I'd love to use that experience to help people who are taking their first steps into the open source community. :)

So, tl,dr; if you're new to programming, and you'd like to try to tackle one of the issues on this project, but you're not quite sure whether to go for it - please get in touch. I will be happy to help you in any way I can - whether that's talking the issue through in more detail so you're sure you understand it, helping you think about how to approach the problem, pair coding with you to fix it together, or any other way I can help - whatever will make you feel comfortable to give it a go!

Today is the official first birthday of this project!

(I actually started a few days before October 1st last year, but I've decided that running 'rails new ShinyCMS' and then trying to fix all the rubocop errors in the Rails boilerplate don't count as 'starting' for purposes of having a nice neat birthday date) :)

I'm pretty pleased with how it's going so far. Although initially I wish I'd realised this anniversary was coming up a bit sooner, as I would have tried to knock a few more things off of the list of "features the Perl version has and the Ruby version doesn't (yet)". Instead I've been doing a bunch of refactoring lately, and actually I have zero regrets about that - one of the great things about this project is that I'm getting to refactor a lot, and it's made a significant difference to how happy I am with the system - both at a zoomed-in and zoomed-out level.

Today I merged the first chunk of work on discussions / comment threads.

As in the original ShinyCMS, the comment threads (and sub-threads) are fully nested, so you can easily tell what's a second/third/etc level reply and see who is talking to who.

To get the nested comments to display with the correct indentation at each level requires recursion*. Understanding recursion is nearing the limit of how clever I get on a good day, so in the past I have occasionally regretted writing this feature when I've had to work on it on a less good day ;) Not as much as I'd regret having written a comments feature with Facebook-style single-level nesting though :)

I added some new demo data (and updated some of the existing demo data) so that all of the current features are covered again.

The reason for including the demo data, and making sure it covers all the features, is so that anybody who's curious can install a dev copy of ShinyCMS locally or on a free Heroku set-up, load the demo data, and immediately play with all of the features of the CMS... without having to do a bunch of boring data entry work first.

Added tags to blog posts, and a Tags controller to view all tags. This was pretty straight-forward, as I'm using ActsAsTaggableOn to do all the hard work. And most of the easy work too ;)

There's obvious scope for abstracting this more at some point, but for now I justed wanted to get the basic functionality working and merged in.

I've been refactoring how themes work, and I'm much happier with it now. With the new set-up it's easy to just override just one or two partials if you want, or maybe just override the layout, but still keep using most of the default partials if they suit your needs. If I can keep the HTML in the default views clean and flexible enough, I think this is going to make theming the hosted site quite low-lift for most normal use cases.

I'm still optimistically hoping that at some point this project will attract some people who just love making and sharing themes :) Design and front-end development has never been my strongest skill, so instead I'm trying to make it as easy as possible for people who do have those skills to come and join in one day!

This PR introduces a Theme model (POR, not AR) which can collect any useful theme-related functionality going forward - utility methods to find out if there's a theme in effect currently, what it's called, where its files are located, what other themes are available, etc etc.

I merged the refactor and rename of shared content today; the feature is called Inserts now (which is a much better name, imho!) and I got rid of the slightly complicated form model thingy that was holding them together, creating an otherwise pointless InsertSet model to do it instead. This makes a lot of the surrounding code much more standard, which I think is an overall win.

I've added the jQuery Smart Menus plugin to drive the menus on the main site, allowing themeable nested menus and so on.

It works okay, although I noticed after adding it that the project isn't very lively, so maybe it wasn't the best choice :-\ I don't really know where to hunt out advice on the best options for JavaScript/front-end stuff like this.

Answers on a postcard in a comment please...

Appropriately, the first merged PR of the year brings us a whole new Ruby - from 2.6.5 to 2.7.0 - as well as updating various gems. :)