proposed: move category group pages out of /tags

[Bloke]

Absolute URL of front-end page

(e.g.) https://docs.textpattern.com/tags/conditional-tags

(see #153 also)

The proposal

Subcategory pages are mixed in with tag documents in the /tags directory. Unfortunately, in order to have a dedicated page for each subcat that lists only the tags in that group, a physical file needs to be present.

Idea:

1. Create a subdirectory: '/tags/group' (I considered /tags/category or tags/categories, but both of those clash with Textpattern's notion of category, which might be confusing). Any better names? /tags/grouped? /tags/grouping? /tags/by-group?
2. Move all current subcategory pages there to clean up the /tags directory further.
3. Alter index.md so the subcategory pages reference the new location.
4. Refactor all the subcategory docs so they draw in a single include file, instead of repeating the broadly similar loops in each file. Pass the name of the group into the include instead.
5. See if it's possible to style/layout the article-listing.html include slightly to make the list more visually scannable. Maybe remove or reword the 'see the full documentation' bit, and hyperlink the heading instead or as well as this?

Thoughts?

[Bloke]

Well that was an exercise in frustration: anyone have any idea what's going on and how to get this to work? I'm obviously missing something really simple. See the commit storm from 49619ee to ef88ba4 to see what I've tried.

Basically, the idea is to factor out the code in all the '/tags/groupname-tags.md' documents so we use one include in each file, instead of repeating the same code over and over. e.g. in the Search tags group:

{% include article-group.html group="Search tags" %}

I want that to dutifully go away and plug in the string "Search tags" anywhere it encounters {{ include.group }} in the following code:

# Group: {{ include.group }}

Textpattern documentation grouped by '{{ include.group }}':

<ol class="list--no-bullets">
    {% for page in site.pages %}
        {% if page.tags contains '{{ include.group }}' %}
            {% include article-listing.html %}
        {% endif %}
    {% endfor %}
</ol>

Except it doesn't work. It plugs the value in the first two and (presumably) plugs it into the one in the for loop itself, but it never matches the page.tags value. If anyone fancies trying to debug this, I've added a call to this include function inside some HTML comments on the search category page.

View the source on that page and scroll waaaaay down to about line 700ish. You'll see the start of the comment, the variable string correctly injected into the text headings, twice, and then 500 or so lines of nothing before the closing </ol>. I'm expecting to see the 9 matching 'search' articles scattered in that blank space.

I've tried different quoting styles, including no quotes, verified that the loop is indeed being executed and returning pages and tags. Even tried capturing the incoming variable into another variable and using that in the loop. Nada. Scanned tonnes of Liquid documentation like this and come up empty. It claims:

contains — a wrapper around Ruby's include? method, which is implemented on strings, arrays, and hashes. If the left argument is a string and the right isn't, it stringifies the right.

Seems to support the theory that the right-hand term will be converted from its internal representation to a string for comparison. But maybe if the left-hand argument isn't a string (is it in this case? who knows) then maybe that conversion's not triggering. I've not found an example of matching a variable with another variable. Maybe it's not possible and Liquid has to match strings? Stupid if so.

If anyone has any clues, I'd love to hear them. @philwareham @bloatware @jools-r @petecooper Bueller? Anyone? Bueller?

[bloatware]

Chinese for me, sorry.

[Bloke]

Yeah, it's kinda like Mustache in principle, but with a slightly crappier syntax!

[wion]

Any better names?

Maybe /tags/types/?

[Bloke]

Works for me.

[Bloke]

Partially done. Still can't fathom out the syntax for using an include so we'll make do with the non-include version for now and if we can refactor it in future, great.