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 page: Index2 #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.