GeezerVison is showing github.com — proposed: change to /tags directory structure · Issue #153 · textpattern/textpattern.github.io
proposed: change to /tags directory structure #153DescriptionJust 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)
- 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:
- It enables setting up consistent use of category include lists for platform categories in the new structure. See issue page: Index2 #144.
- 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.
- 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. ActivityBloke commented on Dec 10, 2019 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 commented on Dec 10, 2019 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 commented on Dec 10, 2019
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 commented on Dec 10, 2019 Great! Thumbs up from me! wion commented on Dec 10, 2019
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 commented on Dec 10, 2019 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 commented on Dec 10, 2019 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 commented on Dec 11, 2019
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 commented on Dec 11, 2019 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 commented on Dec 11, 2019 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 commented on Dec 11, 2019 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 commented on Dec 11, 2019 I'll move the tags back to the /tags directory now and tidy up, unless anyone else has called dibs in the meantime. wion commented on Dec 11, 2019 wion commented on Dec 11, 2019 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 commented on Dec 11, 2019 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 commented on Dec 11, 2019 I guess we need a 'declined' label. Bloke commented on Dec 11, 2019
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 commented on Dec 11, 2019 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 commented on Dec 11, 2019 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 commented on Dec 11, 2019 I'll defer that Q to Phil. philwareham commented on Dec 12, 2019 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 commented on Dec 12, 2019 (i.e. we remove the 4.7 ones when 4.8 comes out) Bloke commented on Dec 12, 2019 philwareham commented on Jul 7, 2020 I think the main scope of this issue has been addressed. Closing now, thanks.
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|