Using eLife journal css as a styling base for eLife's theme

[davidcmoulton]

One question on approach, one on implementation. Happy to split into different tickets if that's easier to manage 😄

Developing an eLife thema theme relies on using eLife's current CSS codebase as a staring point. There are two related questions to answer on how to address this for the long term:

• how does thema reference the eLife styles as its theme's starting point?

• how are these styles consumed by thema in a way that's usable as a starting point?

How should thema reference the eLife styles as its theme's starting point?

The current approach of hot-linking to the css files on the eLife website is not viable long term, Right now I can think of 2 alternatives:

1. As part of the build, getting the assets from the Docker image https://hub.docker.com/r/elifesciences/pattern-library_assets that eLife publish. This is published every time the patterns are updated, and so will always be up to date. Should the recovered assets be included in thema's source control? Seems a bit icky, but git ignoring them might be worse as you could be building the thema theme on top of shifting sands.

2. Getting the assets via an npm module install. eLife don't currently publish an npm module of the code, so this will require setup, but could be built into eLife's CI to publish this at the same point as publishing the image to docker hub. Has the putative benefit of not having to include the imported eLife styles within thema's version control, while also being able to pin to a specific version if / as required.

How are these styles consumed by thema in a way that's usable as a starting point?

The current external http hotlink to the css on the eLife website transforms the css on @import (presumably postcss-import uses the postcss AST) so that, for example, the selector:

.grid-column {...}

becomes

.grid-column, [itemtype~='http://schema.org/Article'], [data-itemtype~='http://schema.org/Article'] {...}

in thema's built CSS file in dist/[elife-css-filename].css.

Local experiments trying to replicate this transformation by @importing either a local css file, or an emulated module in node_modules, both import the css as is, but don't transform it, so it looks like postcss needs to know about the paths somehow. I've tried adding from: [path] into the .postcssrc but that didn't seem to make a difference. Any idea how to get this working? We'll need it to be assured that the current styling approach is viable long term.

[alex-ketch]

Hi @davidcmoulton,

How should thema reference the eLife styles as its theme's staring point?

I agree that the second proposal of publishing assets to NPM would be the most idiomatic in terms of helping with build reproducibility as well as consumption of the stylesheets from Thema (and any other NPM based projects).
I'd be happy to help out if needed to get this approach working.

Barring usage of NPM, I think we could potentially come up with a way to access the assets from a docker image at compile time. Intention there being that we move away from using the ever-changing hash of the hot-linked stylesheet from eLife's website. Downside being that it adds Docker as a dependency, and potentially slower build times.

How are these styles consumed by thema in a way that's usable as a staring point?
…
Local experiments trying to replicate this transformation by @importing either a local css file, or an emulated module in node_modules, both import the css as is, but don't transform it, so it looks like postcss needs to know about the paths somehow

If I'm understanding what's going on here correctly, it's an issue with ParcelJS and PostCSS that has been a bit of a problem for us.
ParcelJS v1 has issues with PostCSS imports that need to compile the entire stylesheet before transforming it.
I will be looking into updating/switching our build process today, and will let you know once this is working.

Let me know if I missed answering anything, or if you'd like to discuss the first question in further detail.

[davidcmoulton]

Thanks @alex-ketch for the thoughts and the context!

I'll put wheels in motion at eLife for developing and publishing an npm module of the eLife published site assets.

The build process issue looks potentially thorny. Interested in what approach you come up with. Feel free to tag me if an extra pair of eyes on code would be helpful (but will be offline for probably the rest of the week soon, so there might a delay in responding).

[alex-ketch]

Glad to hear about the NPM publishing initiative :)
A thought I had as a stop-gap measure for avoiding issues like #62, would be to fetch the latest stylesheet hash at build time, similar to how we run the selector/example generation.
Let me know on if you think it's a worthwhile change, or if you think it'll be obsoleted by the NPM package in the near future.

As for the updated build process, Parcel v2 still lacks some features, so I've migrated to Webpack.
More configuration, but ultimately more control and no more file import issues.
The build process is working, but need to finish development flow configuration. Will ask for your review on the PR once ready.
Thanks and enjoy the weekend!

[davidcmoulton]

I've done a quick check locally, and the migration to webpack seems to have fixed the problem with the PostCSS imports 🎉 Thanks @alex-ketch!