Documentation updates for v5.0.0 - rebasing #1427 #1452
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
In "Whitespace control" page, a new section explains how you can use the liquid tag and echo tag to more elegantly avoid whitespace starting from Liquid 5.0.0 A note has also been added to disclaim that the example output boxes may not have the exact whitespace output expected from the corresponding example input.
Many pages in the Filter section have several Input/Output boxes unnecessarily. Wherever possible, they were consolidated into one set of boxes only. Some documentation have also been clarified further and expanded where lacking.
In Template, some titles are better worded, and some descriptions are clarified. Unnecessary code blocks are condensed. In Variable, real code is used to render the examples instead of hard-coded text.
A bit of magic* splits the filters into categories using a new "category" key in the filter markdown files. All the files stay where they are, and all the URLs stay exactly the same! * The trick is in the various array filters! Note: All filters must have categories. The "aaa" category is a special category that will put those filters at the top under "Filters".
I think these are better taken out of the String Filters category (which is already lengthy) because they don't belong there. In String category, all filters change the final output of the string. But escape belongs with url_encode because they don't change the final output of string (only its encoding). As for split, this actually better belongs in the Array Filters category because it splits a string into an array. Those looking for this filter are more likely to be thinking about array manipulation rather than string manipulation.
Scrollbar now scrolls over to the actual link and positions it at the center of sidebar. This is less jarring that scrolling to the section header at the top. The logo is also moved into the scrollable sidebar but made sticky through CSS. Tested working on both desktop and mobile.
It looked like the filter subheadings like Array Filters were new separate sections in the menu, when it should be a subsection under Filters. This fixes it by changing the boldness and adding an indicative arrow next to the header so that it looks different.
Also apply some DRY principles and minification to the Javascript The filter type links use Javascript to scroll the menu to the filter section. On mobile it will also open the menu. Pretty cool, huh?
It seems in mobile browsers, the padding is not enough to show the menu properly. The auto-hiding location bar of the browser pushes the menu down when visible. It looks better with double padding on both desktop and mobile.
A similar expanded note is already in "render with" so just making sure it's also in "render for".
This also removes the emphasised note that is now unnecessary.
Since this exists and it's currently undocumented, it should now be documented and explained in the documentation. If this will be declared as "deprecated", a deprecation tag can be added later (stating the version number at which this became deprecated). Also, according to the original source file ifchanged.rb the logic is to check the output generated by the code between ifchanged and endifchanged, and compare it to the previous output. The logic is NOT to check whether the loop variable has changed. Even if the loop variable remained the same but there was some other change in the output (for example, using cycle tag), the ifchanged tag will print the output.
Contributor
Author
|
Hello to the project maintainers. It will be nice to get some feedback on this. Thank you! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This rebases my last changes from #1427 and EricFromCanada#1. To preview this, please visit: https://adtc.github.io/liquid/
Individual changes are explained in the commit messages. In short, this categorizes the filters, consolidates example code blocks, and makes several changes in the usability of the documentation website.
Note: I included
ifchangedbecause I agree with this comment. Since this exists and it's currently undocumented, it should now be documented and explained in the documentation. If this will be declared as "deprecated", a deprecation tag can be added later (stating the version number at which this became deprecated).Interestingly, Django's version of
ifchangedhas more features, so I think some do find this tag pretty useful and would want it to be kept around. This documentation also prompted me to check the source code and figure out that it's not the loop variable that's checked for change, but rather the output from the block of code itself.Categorized filters look like this in the sidebar:
