glossary.js should be built from glossary metadata about developers.urbit.org HOT 2 CLOSED

Need to rethink schema and approach — runes, zuse, stdlib all would have too much TOML since they have many many glossary entries on one page. As long as it's pairing content and metadata, it's a solution ...

from developers.urbit.org.

It turns out that we have operators glossary entries! So each site technically has metadata that could be exposed in a glossary.

My current approach:

Splitting up the glossary into metadata entries

1. Creating a script to walk the glossary, strip it to a .md path, and access that file in the directory.
2. Access its data, content variables.
3. Append a TOML entry to the data variable that looks like:

[glossaryEntry]

[glossaryEntry.agents]
slug = "agents"
name = "Print out the status of Gall agents on a desk"
symbol = "+agents"
usage = "Dojo"
desc = "Dojo utility included in the %base desk."

Multiple entries per page would add additional entries under their slug.

4. Rewrite the entire file, pairing the new data with the content it had.
5. Write this as a sequential promise resolver via .reduce().

I'd run this on each site and it would effectively spread the glossary out per page with per-slug entries in the TOML.

Writing the glossary on build

Next I'd write a script like buildPageTree.js to take each page's glossaryEntry sections and compile them into a .js file that gets cached.

I'd deploy this for each site's build process.

Rewriting search logic to pair glossaries and search results per website

At first I thought, why not have the developers website build its glossary from other sites' glossaries and serve as the source of truth? The trouble is that if another site's glossary updates, the source of truth won't update until that site rebuilds, causing unpredictable behaviour when changing docs.

Instead, I should change the APIs per site to search both their own glossaries and search results and return a pair. The search rendering logic on each site should then expect to split up the data accordingly and make them into one big glossary section and one big search result section. This seems like the best option for keeping results current while maintaining current performance.

from developers.urbit.org.