ex_doc
ex_doc copied to clipboard
elixir-lang
Move to esbuild
We will probably need npm still, for handlebars, but it should streamline things considerably.
The next step would be to submit a PR that replaces webpack by esbuild. Please let me know if you have any questions. :)
The goal is to completely remove webpack. If we can remove npm altogether, even better, but I think we need npm for handlebars and perhaps running tests? There is a guide on how to use esbuild with plugins here: https://hexdocs.pm/phoenix/asset_management.html
@sigu, it sounds like you're taking this, but let me know if not as I'd be happy to have a go in between other bits over the next few days.
@josevalim, I wondered if this would be a good time to remove Less for CSS. I tend to use plain CSS now as browser support for custom properties (variables) is good.
Ah, I forgot about less. I think we can definitely consider removing it. Perhaps before moving to esbuild. Do you want to analyze how doable doing so is? Thanks!
Sure - will do at some point this week hopefully, unless @sigu chooses to look at that part before I get to it. :)
Hello @DavidOliver I will have a look at how doable it is in the next few hours and share my findings. You can also have a look in parallel
I tried my hand at this yesterday and Less was very problematic. Especially the '~' (tilde) resolution to node_modules. There's a referece for this problem here (https://github.com/evanw/esbuild/issues/20#issuecomment-803281141)
So, if removing Less is an option, I think it is a good one.
Hello @DavidOliver I will have a look at how doable it is in the next few hours and share my findings. You can also have a look in parallel
Hi @sigu. What's the state of play with this your end? I started to have a quick look through the less files and saw that some reworking would be required with regards to nested selectors and content variables. I'd be happy to take a look at handling the switch to plain CSS next week if you'd like?
@josevalim, while I'm going through all the CSS, should I remove styles and assets that were added to support now-out-of-scope(?) browsers such as IE and old versions of current browsers? E.g., removing all font formats except for woff2.
@DavidOliver
I played around with the lessc command line tool and got a working version with less completly removed (see https://github.com/moogle19/ex_doc/tree/less_less). It didn't produce the most beautiful css but could be a good starting point.
@moogle19, cool - thanks. Based on a very quick look, my approach is a more manual (and slow!) one, giving attention to each included file, and I'm preserving comments and the specifying of alpha values in the main CSS by separating out h, s, and l values in the custom properties where necessary. I'll carry on in this vein with long-term maintenance in mind, but it's good to see you've got it all working.
I hope to carry on and update here this week.
Sorry for the long delay. I've since moved, and I'm hoping to be in a position to resume work on projects at some point next week.
I've now picked this up again, and have rebased and incorporated the improvements to dark mode made since I started removing Less. I'll continue working my way through the remaining Less files.
(Sorry again!)
Initial run-through mostly complete. I'm now reworking how custom properties are used and tweaking some selector blocks in order to cut down on highly repetitive selector rules and to avoid the need to re-set colours in the 'night' files.
E.g., we can define most colour custom properties for light and dark upfront as follows:
:root {
--warningBackground: hsl(33, 100%, 97%);
/* ... */
}
body.dark {
--warningBackground: hsl(40, 67%, 79%);
/* ... */
}
Then we only need to set most color properties once:
.content-inner blockquote.warning {
background-color: var(--warningBackground);
}
And no longer need to additionally set the dark theme color properties as at present:
body.dark .content-inner blockquote.warning {
background-color: #edd5a5;
}
This and other adjustments are taking some time to work through, especially as I'm not already familiar with the ExDoc epub and HTML output meaning I'm having to be careful when checking the results, but I think it will be worth it as there will be less CSS and it should be easier to maintain/update.
PR to remove Less CSS submitted. I can also have a go at moving to esbuild, but I thought I should get the removal of Less CSS in before any more styling changes are made if possible. :)
Status update: the main/basic build using esbuild is working. :partying_face:
Handlebars was the biggest issue; I worked around not being able to get either of the available loaders to work by setting up precompilation of the templates, which I think in theory saves some processing power in the browser.
I'm yet to check that things like the optional logo and extra assets are working, but will do before submitting the PR.
For this move to esbuild, should I include the changes to files in formatters in my commit? I ask as the readme says not to when contributing.