Folder/file architecture for a glossary project

Help
1

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.

Context…

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.

Index page

What I envision are lists of terms organized by alphabetic letters. For example:

A

B

C

  • etc

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:

C

D

T

  • 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.)

Definition page

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
  • title
  • summary
  • authors/affiliation
  • definition
    • 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?

2

Cool project. I recommend using a collection for your glossary (e.g., _glossary), rather than pages or posts. In your collection, define all the sections for your template as properties in the YAML front matter. For example:

---
breadcrumb_path: 
title: 
summary: 
authors: 
definition:
references:
---

You can define a stylized layout that specifies where each YAML property should go.

For example:

{% for term in site.glossary %}
<div class="mybreadcrumbstyle">{{term.breadcrumb_path}}</div>
<div class="title">{{term.title}}</div>
...

In YAML, you can use HTML. To give yourself more space, use this format in your definition:

definition: >
  this is my definition.
  
  this is a new line...

For the index page, you just create a new page with a new loop and loop through the properties you want. (term.url would go to the collection’s url.)

3

Thanks, @tomjohnson1492 . I’m happy to see you in here. There’s some clues to the puzzle in there for sure.

I should probably mention I’m using GitHub Pages for this, thus the Jekyll that’s already baked in. The file tree is a dedicated repo to the glossary. I don’t know if that makes a difference about using a collection, but it seems odd to put all files into a subfoder in that case.

Also, I do not have Jekyll installed locally (yet). :slight_smile:
I was kind of hoping to avoid that because this project will not be one that accepts pull-requests. You have to actually be an “outside contributor” on the repo, thus will have direct push rights. But for now it’s just me getting the architecture, templates, and protocols in place.

I’m still getting my head around yaml front matter and Liquid, but the basics are coming along.

Most of the HTML for a definition is handled in a layout template, definition. Everything in the markup files get’s inserted in the {{content}} tag, of course.

You can read more about what’s going on so far in the project wiki, which is still a little bumpy. And here’s an example file that’s not fully marked up as desired yet. I’m using that one to get the Liquid build in place for definitions. Once that part is done, I’ll fold in the accessibility and semantic attributes.