I’m a first time Jekyll/YAML/Liquid user and slowly getting my head around it. I think I have the basics down, but I’m going to have some questions for sure. Here’s the first one, it’s just high-level about file tree architecture.
The project is a rolling, collaborative glossary. The main index page will serve as a glossary index, and all other pages in the site are definition files. (There should be a search page later.)
My questions at the moment are with regard to how best to structure the file tree so that I can more easily organize the index content. I’m just getting started with an index page and 3 definition files to test, so it’s no big deal to move things around if necessary. I’m hoping to get an idea about the big picture structure so I more or less get it right before the bulk of files is created.
What I envision are lists of terms organized by alphabetic letters. For example:
My initial thinking is to use pages for definition files, not posts. The definition files are not going to have comments and whatnot – they’re just static reference pages.
I was also hoping to keep everything in the root directly (a true flat tree), not have to organize all the pages into subfolders, but I’m flexible on this if it’s necessary to design the index easier.
I also expect to use breadcrumps at the top of each definition page. But I’m not sure yet how to do this effectively. Based on the above lists, the obvious outcome would be, for example, Index > B > Buffalo. But I’m expecting to use tags in the glossary too that can filter glossary terms by a related theme or concept. I’ve not figured all that tag stuff out yet.
I also expect to use previous || next pagination in each definition so it’s possible for a user to move through the glossary laterally, one definition page at a time, regardless of how the file might be organized in folders (or not). Assuming that’s even possible.
Finally, another twist to this architectural puzzle… a given term will link to the definition file, of course, but there will be two types of terms in the index lists, alphabetized together: the primary terms themselves (definition file links), and secondary (related/synonymous) terms that have a redirect to the primary term’s definition. For example, here ‘cat’ and ‘dog’ are primary terms, and the others are secondary terms that point to the primary definitions:
- Tabby cat (see Cat)
The reason there are primary and secondary terms is to eliminate needless redundancy in the glossary. Related (secondary) terms are addressed in the main definition file. (In case you’re wondering, the determination of what term gets to be a primary term vs. a secondary term is part of the collaboration process, which is out of scope here.)
Each definition file will have a very uniform structure, with as much of the more complex HTML serialized out as front matter to make it easier for collaborators to work with. (I have another challenge about that for a different help post.)
A definition page’s top-to-bottom structure:
- breadcrumb path
- primary explanation (one or more paras)
- [if relevant] Figure (anywhere between primary paras, but not before first para)
- [if possible] Real-world example(s) (a para+ for each example, one preferable)
- [if relevant] Explanation of related/synonymous terms (one para per term).
- References (marked up as footnotes)
That helps you see the relationship between primary and secondary terms.
So, any suggestions/ideas/watch-outs about the architectural approach to the main index?