search

Shopify / liquid

Liquid markup language. Safe, customer facing template language for flexible web apps.
https://shopify.github.io/liquid/
MIT License
11.07k stars 1.38k forks source link

Add source map for built HTML files #1047

Open fulldecent opened 5 years ago

fulldecent commented 5 years ago

Liquid can be thought of as an HTML compiler. This is similar to SASS CSS compiler or a Javascript minifier.

When debugging a compiled project, it can be helpful to know the origin of each line of the output. For example, if a built html project using liquid (maybe through Jekyll) may contain this HTML error: <img src="url"> (it is missing an alt tag). Normally it would require a human to figure out which include file this error originated from.

In modern times testing is usually done automatically (maybe Travis CI running against a website published on GitHub). It will be nice if the test errors, which are based on the built HTML, can be automatically traced back into the original source code, the Liquid files and partials includes.

There is a standard for this already and it is called Source Maps. This technology is widely used for CSS, JS and Solidity compilation as well as other languages I'm sure.

I believe this is the authoritative documentation: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit

An implementing library: https://github.com/mozilla/source-map

Please consider to implement Source Maps for Liquid.

pushrax commented 5 years ago

This is a good idea, and I don't think it would be super difficult. Good intern or hack days project.

To be clear, the scope here is not to validate HTML in Liquid, but to provide a mechanism to emit a source map along with a render, so a downstream tool (or a human) can map the output back to the source. This is useful when validating HTML, but also when simply reading the output.

Overall priority is low here for an internal contribution, since the "search all the files for the string" approach works for Liquid as it doesn't transform input outside of tags. It would be a quality of life improvement in some cases though.

fulldecent commented 5 years ago

Thank you, and yes that scope is correct. Prioritization seems correct.

I am on the html-proofer project so we can use built html errors + source map = Liquid source errors. If you have Liquid in a repository (like every website hosted on GitHub Pages) then now we can automatically highlight the lines that are errors.