diff options
| -rw-r--r-- | doc/todo/concatenating_or_compiling_CSS.mdwn | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/doc/todo/concatenating_or_compiling_CSS.mdwn b/doc/todo/concatenating_or_compiling_CSS.mdwn new file mode 100644 index 000000000..ed3f2e846 --- /dev/null +++ b/doc/todo/concatenating_or_compiling_CSS.mdwn @@ -0,0 +1,110 @@ +It would be great if IkiWiki could apply some sort of preprocessing to +CSS. I'm just "thinking out loud" at the moment, but I might write +a plugin. + +The simplest starting point would be concatenating a list of files: + +* The actiontabs and monochrome themes are not ready for use as-is; + the Makefile constructs the real stylesheet by concatenating the + anti-theme's CSS and the relevant theme's CSS. It would be better + if they could just drop a file in an underlay, and IkiWiki would + concatenate the anti-theme stylesheet and the theme's file. + +* The blueview theme is the same, but the theme's CSS also starts + with a couple of stylesheets from YUI. IkiWiki could maybe + concatenate the anti-theme stylesheet, the two YUI stylesheets + and the blueview-specific part? Or maybe that's too complicated. + +* The goldtype theme is the blueview theme with some overrides + added to the end. Again, IkiWiki could concatenate all the pieces. + +* The [[plugins/contrib/album]] plugin needs to append some + stuff to the stylesheet, making its installation more involved + than it ought to be. If it could append the pieces by putting them + in an underlay, installation would just be a matter of "add + the files". + +I'm not sure whether local.css should be concatenated too, or whether +it should be separate. + +It would also be great if the same mechanism could be extended +to compile CSS-like languages like [[!debpkg ruby-sass desc=SASS]] +or [[!debpkg node-less desc=LESS]] down to CSS, but for dependency +reasons, I don't think the themes shipped with IkiWiki should rely on that. + +If the compiled CSS ended up with a content-based filename (perhaps +ikiwiki/compiled-HASH.css where HASH is the (possibly truncated) MD5 or SHA1 +hash of the content), that would mitigate stale CSS being served from cache +(as long as the HTML has a short expiry, which is desirable anyway), +and ikiwiki-hosting could maybe even do something like this to allow +long-term caching of the files with content-based names: + + <LocationMatch /ikiwiki/compiled-[a-f0-9]+\.css> + ExpiresByType text/css "now plus 1 year" + </LocationMatch> + +A similar mechanism could maybe be used to minify JavaScript. + +## vague syntax proposal: controlled by directive + + \[[!css files=""" + style.css + ikiwiki/plugin*.css + ikiwiki/theme*.css + local.css + """]] + +* *css* directive, placed in any page, concatenates the given files + and uses them as the stylesheet for that page and its subpages, + replacing `<TMPL_VAR BASEURL>style.css` + +* the files can be globs, which are sorted lexicographically within + a glob, and do not have to match anything (so it's OK if you don't + have anything that matches `plugin*.css`); "-" happens to sort + before ".", so theme-base.css would sort before theme.css, + which is nice to have + +* the default would be `style.css`, then `ikiwiki/plugin*.css`, + then `ikiwiki/theme*.css` and maybe `local.css`, as in the + example above + +* `style.css` would continue to be the anti-theme + +* themes would ship `ikiwiki/theme.css` instead of `style.css`, + resulting in concatenation + +* goldtype would ship `ikiwiki/theme-base.css` (which is a copy of + blueview, or a symlink to blueview if we can make symlinks safe) + and `ikiwiki/theme.css` (which is the goldtype additions) + +* [[plugins/contrib/album]] would put its templates and + `ikiwiki/plugin-album.css` in an underlay + +* any non-contrib plugin with complicated CSS requirements + could also move its CSS to an underlay + +I think this could be done entirely in a plugin, except for this +change to `page.tmpl` to allow the `<style>`s to be overridden: + + <TMPL_IF COMPILED_CSS> + <style type="text/css" href="<TMPL_VAR BASEURL><TMPL_VAR COMPILED_CSS>" /> + <TMPL_ELSE> + <!-- ... what it does now ... --> + </TMPL_IF> + +The plugin could also optionally minify its output, and either pass input +files through an external SASS/SCSS/LESS implementation according +to their extension, or have a hook system to do so. + +People who want SASS/LESS would probably just do this in their top-level page: + + \[[!css files="mywiki.less"]] + +and do the inclusion/concatenation logic via @import. + +Security consideration: the SASS/LESS compilers will read arbitrary local +files, so if you use those languages, ability to upload the appropriate +extension would have to be locked-down. Perhaps it's better to implement +this without that feature initially. + +--[[smcv]] |