Make theme reusable by other Open Knowledge sites about opendatahandbook HOT 14 CLOSED

My original plan was that the split would be between master and gh-pages. I stopped committing to master when we started working on content, so it should just be a case of checking the content is generic, and cherry-picking the theme related commits. I'm happy to discuss further of course.

Would probably be a good idea to have a more concrete idea of what is required of the 'standard theme', before going too far in any direction.

from opendatahandbook.

Good questions Sam. Here are some initial user stories:

• As a site Developer I want to reuse this theme quickly and easily
  • Quickly customize the site logo, set google analytics etc
  • For more complex customization e.g. menu I want to have simple instructions in the README
    links and you are go.
• As a Developer I (may) want to customize the theme and esp the HTML so that I can tweak the appearance of my website
  • preference for bootstrap esp in html structure as that is common across OK
  • JS / CSS relatively clear and clean (e.g. bootstrap base distinct from what we layer on top of it)

from opendatahandbook.

Thanks. The first story makes sense, I'm not sold on the 'hows' in the second story though. For much the same reasons as before.

• HTML should (ideally) have little bearing on appearance.
  • Bootstrap, when used correctly should not impose an HTML structure.

Is the user story implying that there should be access to some commonly used, pre-styled HTML elements? Or is it perhaps that the developer specifically wants access to Bootstrap mixins?

To reiterate, if the developer in your user story is (only) writing HTML, they should not need to know what framework is behind the CSS. If on the other hand the developer (only) wants to change the appearance of the site, they should not need to touch the HTML.

from opendatahandbook.

Bootstrap does have a structure e.g. column width classes. Not a "structure" but css classes etc.

from opendatahandbook.

Sorry, "when used correctly" is probably not very helpful (and a little subjective). I am aware of Bootstrap's representational classes, but I am advocating for semantic HTML. Especially in this case, where the semantic HTML (and corresponding CSS) is already complete.

This does not preclude the use of Bootstrap as a framework in production, but it does, in my view, mean we should use it in a different way to what you are suggesting.

There's an overview to the approach I have towards Bootstrap here.

So I'm just trying to get to the heart of the user story, to ensure we find the best possible solution (to fulfill this as well as our own story of wanting to do excellent work).

from opendatahandbook.

CCing @pwalsh as the more general issue here may impact development.

from opendatahandbook.

The point here is that Bootstrap is familiar and common and people do need to actually use the column widths etc. if we go the semantic route it may be nicer from design (i agree btw) but likely harder for non-design folks to understand, adapt and modify (?).

from opendatahandbook.

Agreed, it would probably be easier in that respect. I would question the merit of such changes, and suggest that the template should cater for the requirements that are reasonably asked of it, but that's perhaps beside the point.

If that is indeed the user story here (As a developer I want to alter page layouts and/or appearance of elements, using Bootstraps representational classes), then my previous estimate is no longer valid. We would now need to rewrite pretty much every line of code. In this case I think we may as well start this from scratch.

from opendatahandbook.

@mintcanary and how long will that take? I'm sorry to task this but i never realized we weren't running off boostrap and should have made this even clearer from the beginning in February.

from opendatahandbook.

No problem. I guess around three days.

We should create a list of what pages/sections should be included in this version. For example, the resource library may not be required?

from opendatahandbook.

I'm just thinking the basic theme here not page specific stuff as being common - that's the stuff we'd extract out.

Perhaps worth sharing my understanding of how one layers css in projects:

base-template.html
/css/style.css  # imports other css and tweaks for this project
/css/bootstrap.css
/css/base.css  # our base overlay
/css/some-particular-stuff.css (e.g. perhaps for particular page or behaviours)

I would imagine that maybe the bootstrap, base and particualr stuff would like in the common repo (e.g. jekyll theme) and then a given project import those (from remote url) and adds own local tweaks in local style.css.

Does this make sense?

from opendatahandbook.

Sure, but if we ignored the existence of content altogether there'd not be much of a theme. So all the theme needs to do is format content in a suitable way for documentation/articles? Would there also be a homepage layout?

There are two ways I could interpret those CSS layers.

Custom Bootstrap
Stuff outside the scope of Bootstrap
Page specific stuff
Blank file intended for tweaks

or

Default Bootstrap
Custom Bootstrap
Stuff outside the scope of Bootstrap
Page specific stuff

I suspect neither of these interpretations are quite what you have in mind though, as in neither of these could you make a case for more than two files being in a common repo. (Also, in the second interpretation, the first file would likely be redundant.)

from opendatahandbook.

I suggest we migrate this issue to somewhere like https://github.com/okfn/jekyll-template/issues and close this.

@mintcanary wdyt? are you happy to migrate the summary and then close this with a link to the new issue.

from opendatahandbook.

OK, done okfn/jekyll-template#5

from opendatahandbook.