proposed: change to /tags directory structure

[wion]

Just a proposal to sit and think about. Nothing to railroad through.

The current structure of the /tags directory has the following items (if I'm not missing any), plus a whole-lotta tag pages...

• tags
  • shortcodes
  • tag-basics
  • index.md
  • article-tags.md
  • comment-tags.md
  • conditional-tags.md
  • deprecated-tags.md
  • error-handling-tags.md
  • file-tags.md
  • future-tags.md
  • image-tags.md
  • language-tags.md
  • link-tags.md
  • markup-tags.md
  • navigation-tags.md
  • programmer-tags.md
  • search-tags.md
  • structural-tags.md
  • tag-attributes-cross-reference.md
  • tags-in-development.md

Conceptually speaking, the index.md is currently serving as a 'reference index' for all the tag pages, as opposed to giving all the items in the /tags directory equal weight. As a result it's difficult to find everything available, and especially if the homepage index does not list all the pages (and it currently doesn't).

I'd propose the following kind of structure instead, which accounts for everything as a start (items in bold are new):

• tags
  • reference (all tag pages only here)
  • . . .
  • index.md
  • . . .
  • shortcodes
  • conditional-tags.md
  • deprecated-tags.md
  • index.md
  • learning-tags.md ('tag basics' becomes a single doc)
  • structural-tags.md
  • tag-attributes-cross-reference.md
  • tags-in-development.md

The revised structure offers several benefits:

1. It enables setting up consistent use of category include lists for platform categories in the new structure. See issue #144.
2. It better organizes the parent category directory, separating tag pages from other pages, and provides a dedicated and proper index to tag pages, so the existing reference index can be easily replaced, if but by a new link.
3. In the case of 'tag basics', we can reduce the number of pages needed by merging those files into a single document; each becoming a section. It works in this case because: 1) most of the files are quite short, and 2) they all fit a common theme/objective, which is to learn Textpattern tags. A single document is thus easier to link to for that purpose and maintain as a narrative from beginning to end.

The only negative from all of this is breaking links to the main index.md page that people likely have come to see as the 'Tags Reference'; and not surprisingly, because that's how the directory was made to appear, though it wasn't the sole function.

IMO, the compromise is worthwhile for the benefits gained by a more logical structure. And since we now have root-relative links working, all in-page links to tag pages should not be affected, only the few links to the 'tags reference'. But since that will now just become a clear link on the main page, and the new index list (No. 1 above), the 'reference' index is still easily findable by the old link, and will still look exactly the same when people arrive there. Everything will smooth out in short time, I'm sure.

cc-ing the folks who have a vested interest in this: @philwareham, @bloatware, @bloke, @petecooper

Checklist

Checklist moved to #155 since we're not moving tag pages.

[Bloke]

Fine by me. Links can be fixed, and with the proposal to put links to common things that have moved on our 404 page, I think people will be able to update any bookmarks easily enough.

[philwareham]

As long as the alpha index of all tags stays somewhere, and all tag documents are relatively unscathed - then is fine by me too.

[wion]

As long as the alpha index of all tags stays somewhere

Yep. It will stay exactly the same, just here, /tags/reference/index.md, instead of here, /tags/index.md. And you'll appreciate knowing that when working in that directory, every file is only a tag page (except for the index).

[philwareham]

Great! Thumbs up from me!

[wion]

I think people will be able to update any bookmarks easily enough.

Oui. When we get the index2 put to top, we can make a proper community announcement about the changes, maybe even a blog post is worthwhile. A short one.

[wion]

Okay, I have the /tags/reference/ directory in place, and a copy of all the tag pages operating through index2. Does anyone know how to run a find/replace on the pages in that directory to change the yaml category from Tags to Tags reference?

Otherwise, that's a slow 167 page slog of manual-gradualization-changin'.

Someone might want to peruse the reference directory, too, and ensure only tag pages are accounted for. (Plus the index, which is there.)

[wion]

If any changes are made to /tags/ versions of pages, make a copy over to the /reference directory. Or, we could just get the show on the road and roll that new directory out as soon as category fields are changed.

[wion]

Does anyone know how to run a find/replace on the pages in that directory to change the yaml category from Tags to Tags reference?

Done. And tag page links have been updated in the /reference/index file.

[wion]

All work on this issue as proposed is now done, except for the spin-off doc for #154. A forum announcement has been made about tag link changes. Please review changes for any anomalies. If everything looks okay, assign issue back to me to remove tag pages from /tags directory and we work hereon via /reference directory.

[Bloke]

Nice work. The only thing I see now is that any tags that mention 'other tags used' (primarily in the examples) link to the bare '/tags/tag_name' docs, so those links will all need updating.

The tags all need a comb-through anyway to remove references to the panel page docs and to update them for 4.8.0, so this can be done as part of that exercise.

[wion]

Arg. I just noticed that too. So we need a checklist, then.

[Bloke]

Probably.

[wion]

Speaking of which, are those in-page links that spell out the obvious about other tags used in examples something that really needs added? I guess it does make for an easy lateral jump, for the curious. But a pain to maintain.

What if instead of naming specific pages in those places, itself more editorial overhead, we just include a link to the main index, for example:

Find all tags used in this example via [Tags index]().

I mean, a lot of examples are kind of hypothetical/arbitrary anyway. I doubt many people are using those links if they're only interested in the one tag they're reading about.

[wion]

Checklist added to head post.

[philwareham]

I'd prefer to keep the 'Tags used' links please.

[Bloke]

I would prefer to keep them too. Once the links are updated to this new (more logical) doc structure, they shouldn't need any additional maintenance. The tag names - and hence doc destinations - don't usually change.

[Bloke]

I don't mind taking my share of tags and updating them in tandem with the 'history.txt' file to update them for 4.8. We could really do with some better examples too, as we go. Some of them are a little pointless.

[wion]

I'd prefer to keep the 'Tags used' links please.

Keeping.

I've started updating links. Note the other needed revisions at the top of the checklist. Add what is missing.

[wion]

A clarification on this item on the checklist:

4. Remove links to 'Page/Form templates explained'. Those links are not determined/stable/assured yet.

That's referring to two pages that were in the /themes directory. I didn't know they were linked to from tags pages because of their location in the /themes directory. (An example of why the systematic use of Issues for existing and proposed pages will be valuable. Easier to see and track such intentions in collaboration.)

The pages doc was nothing but an empty draft file, with yaml and a few headings. I removed it. The forms page has been moved to the /build directory and the 'Themes: Creating...' doc I'm editing links to it in an early section.

But, here's the thing: When the 'Site structures' doc gets written (#152), both of those kinds of files would likely become obsolete anyway, and the new file would be the one to link to in cases where the ideas of 'templates' needed to be referenced (such as from the Themes doc).

Just so you know what happened there.

[wion]

I was just looking at this page (a correct/unchanging location)... https://docs.textpattern.com/tags/article-tags

And it lists all the tags twice. One with the correct path and one not. I'm guessing there's some liquid voodoo going there that's picking up both sets of tag pages?

So how about as we do the checklist sweeping and update pages in /tags/references, we remove the corresponding pages in /tags. They will be outdated at that point anyway.

[Bloke]

Sure, let's do that.

[wion]

Added another item (inserted as item 3) on checklist sweep. In these cases, just ignore it but put a '3' next to the checklist item that has any such link. I'll go back and fix those myself when done with #154, as noted.

[wion]

Amendment to that previous post: It appears most links to the 'tags-basics' stuff is in relation to the escape attribute. No need to mark these with a '3', in fact, because I can just use the cross-reference page via that attribute to find them. ;)

[wion]

And it looks like referring to this issue via sweep commits is a bad idea, or we'll end up with 160+ of those annoying bookmarks here. Aieeee!

[wion]

Sorry to bombard you, but this stuff is probably helpful...

In relation to this checklist item 4, go ahead and use these links:

• [page templates](/build/site-structures#page-templates)
• [form templates](/build/site-structures#form-templates)

I will make sure those sections exist in document #152 to satisfy any such links.

Attention: In this use, 'page' and 'form' are regular adjectives, not proper adjectives, so do not capitalize them unless beginning a sentence. A proper adjective would be something like 'the Forms panel', because it's the name of that panel being used as an adjective on 'panel'. Otherwise, always lower case. The links alone will help with the distinguishing in this case.

For example... https://docs.textpattern.com/tags/reference/meta_keywords

[Bloke]

I'll move the tags back to the /tags directory now and tidy up, unless anyone else has called dibs in the meantime.

[wion]

OK.

[wion]

It's a bummer because it ruins being able to use includes consistently for all the homepage and primary indexes. A bit convoluted now with tags.

Question now is, what should be the subdirectories fix inside /tags?

• tags
  • ??? (for the few remaining pages, like cross-reference, etc)
  • categories
  • article-tags.md
  • deprecated-tags.md
  • links-tags.md
  • . . .
  • shortcodes

[wion]

I wonder if the shortcode's introduction (in index.md of that folder) should go in the learning tags doc (154), and the shortcode examples docs get published in Textpattern Tips instead. They're all community/custom spins anyway that will never be updated unless forum editors do it.

That would reduce the /tags directory to just two subdirectories:

• tags
  • categories
  • extra (for few remaining; e.g. cross-reference)
  • tag-page.md
  • tag-page.md
  • . . .

[wion]

I guess we need a 'declined' label.

[Bloke]

It's a bummer because it ruins being able to use includes consistently for all the homepage and primary indexes.

Can we use conditionals inside the includes?

I wonder if the shortcode's introduction (in index.md of that folder) should go in the learning tags doc (154), and the shortcode examples docs get published in Textpattern Tips instead.

If you think that makes sense and jools is cool with it, then it works for me too.

[wion]

I don't know about conditionals. Above my liquid grade.

I don't know if it's better. Probably doesn't make any difference in this case. What's one more directory if you already need two.

[Bloke]

Okay, tags should be back to as it was before.

Question: on the tag index page, do we need to keep all the 'modified 4.7.x' annotations or can we ditch them and only mark up the ones that are changed / new in 4.8.x?

[wion]

I'll defer that Q to Phil.

[philwareham]

I'd prefer if they stayed in some capacity. I was thinking at each major release (i.e. 4.8.x) they would be added/removed so they are immediately apparent what has changed at the current release (including it's minor point releases). It should be quite easy to do since we have a history file that lists any changes to tags (or at least should).

[philwareham]

(i.e. we remove the 4.7 ones when 4.8 comes out)

[Bloke]

That's perfect.

[philwareham]

I think the main scope of this issue has been addressed. Closing now, thanks.