👷‍♀️ Add Build Process for Definitions

[ovlb]

Hi!

First of all: This is not done yet. But I would rather get some feedback now, or at least hints if the direction can work out. :)

This is also does not yet handle multiple definitions as proposed by @good-idea in https://github.com/tatianamac/selfdefined/issues/13#issuecomment-548979863.

It is basically a compromise of being human editable, but machine parsable. With a better automated editing process we will probably get closer to not-human-editable. One learning so far: Dictionaries are very hard to do right.

I added Eleventy and this is nice. Definitions (for now just some test cases) live in 11ty/definitions. We can add one .md file per word, put in some front matter (e.g. for title, flags and alt-words) and write the definition itself in Markdown. This is not fully specced out and especially the rendering/applying the existing styles needs more work.

I have done some updates to the markup here and there (e.g. the alt words are now a list to make more sense for assistive technology).

You can test this by running npm install in the project root and npm run watch afterwards.
There is no real dev server yet. CodeKit should work, but as this is not a resource everyone can afford, there needs to be some more work done on that side.

Also, if we would get one dollar for every instance of me failing to write «definition» the project would have a very solid financial standing now. 🙈

To-Do

• Finalise parsing of defined items (flags, definition content)
• Make it possible to have child items in the table of content (probably through front matter objects)
• Accessibly handle Emojis in titles and definitions
• Split ToC in groups
• show items starting with - in the appropriate alphabetical place
• Port all the definitions (some sub terms missing)
• Write documentation for definition file structure (in progress)
• Dev Server
• Build process for (S)CSS
• Production build for everything

[tatianamac]

This is so lovely, @ovlb ! I appreciate all you've done so much. 😭
I've included a few initial thoughts below, but if there's something specific you want feedback on, please let me know.

Generally speaking, the structure so far seems intuitive and really helpful. I can see how to evolve it. Now that I'm writing more definitions, I can see more use cases and needs.

1️⃣ I believe based on how you write it we can add basically infinite headers to create the needed sections. I have ideas as to how I want different types of definition types to be structured. Maybe we could set a few template types for words?

2️⃣ Can alt-words be linked from FML in some sort of automated way? For example, can we somehow run a script to see if any of the alt words is present in the dictionary, and if so, automatically link it?

3️⃣ I'd like to be able to match the styling a bit more closely to the page, but this is a less critical thing to influence later.

I'd also love @zachleat to weigh in about this general approach, and share if there are any other ways we could use Eleventy intelligently.

[ovlb]

Hey Tatiana,

Glad to hear that you can work with and understand the updated structure.

1️⃣: Yes, correct. Currently, you could go free form with the definitions. Adding example files which outside contributors can copy to write their own definitions is on my to-do list. I would maybe add a folder where these examples can live? We can link to that folder from a contributing.md to make them discoverable.

2️⃣: This should definitely be possible in the build step or through a template filter. I’ll have a look later.

3️⃣: Working on it. :)

OMG, you tagged Zach. I will hide under the rug for now. 😜

With warmth,
Oscar

[ovlb]

@tatianamac I’ve added a filter to link to defined alt words (added unreal.md to test it in the list of crazy).

Also, the styles match the original better. Still, way to go, but getting there :) As the styles now rely on a bunch of sibling selector trickery and display: grid I currently can’t rebuild the grey line separating sub-headlines and adjacent content if there is more than one paragraph in the content. 😔

[zachleat]

This looks great! My only high level piece of feedback is that you might be able to use one collection for definitions and definedWords somehow? You may even be able to get away with removed the defined key in each word front matter and tying that to word.templateContent.trim().length instead? Just one less thing to keep in sync manually

[zachleat]

Oh one more thing based on your comments I just want to make sure you’re aware of eleventy --serve, which is a hot-reloading version of --watch

[ovlb]

@zachleat Thanks so much for your kind feedback :)

re one collection: I tried that, but the template was complaining about me trying to filter at one point. That’s why I went with two separate collections. In hindsight, it also makes the linkIfExistsInCollection filter easier to grasp. Though I would lie if I say this is part of the initial reasoning. It was me being lazy.

re checking for template content: That’s a nice hint! Upside I see with the defined toggle is that we would have an easy way to hide definitions that become outdated or disputed without deleting files/content permanently. I would like to have @tatianamac’s opinion here.

And I totally missed --serve. Tak! 🙈

O*

[ovlb]

@tatianamac The docs are very much work in progress. As a matter of fact, I wanted to discuss proper examples with you. I just started writing and maybe got a bit overenthusiastic.

Thanks to the power of document.querySelectorAll() I’ve ported all definitions. Yay. Just need to add flags and sub-terms. This and the build process and I am done, I guess. I would take the emoji handling into another PR, as it is not strictly related.

[ovlb]

I somehow have a hand for PRs that escalate quite quickly. 🙈

[ovlb]

@tatianamac Data Processing is done 🤖

[tatianamac]

@ovlb Can we consider this PR closed (asbuild process for definitions is the core task here)?

I'd ideally like to open a few new issues of things you ambitiously included on your to-do list (and got amazingly far on—thank you!).

• Build out contributing.md
• Enhance emoji support
  ... Am I missing anything else?

[ovlb]

@tatianamac Yes, almost. I would like to add the build process so that the Netlify deploy works seamlessly. I will do it this evening. The other open items can be handled in separate Issues/PRs. I will split it iup, after adding the build config.

[tatianamac]

You're so helpful and wonderful! Thank you! 🙏🏽

[ovlb]

@tatianamac You are too kind. Glad I can help with this project.

Build config is now existing, Netlify works. I think you can merge this. 👩‍🚀