ffmprovisr structure: code modularity for better organisation, multilingual support, etc

[kfrn]

In the past, we've had some discussions that relate to the technical structure of ffmprovisr:

• Discussion: refactoring index.html into individual recipes to be loaded as one #309
• Translations? #416
• ffmprovisr en español (2025) #485 (comment)

I'll pull over some parts of my comment on the español translation (the third link).

Currently, all recipes are in a giant HTML file. To add a new one, you simply cut and paste the template, uncomment it, and fill it out.

Pros:

• no compilation step: you can simply open the HTML file in the browser
• easy and user-friendly to contribute to

Cons:

• we cannot easily support multiple languages
• the HTML file is very long and unwieldy
• the current approach may lead to a lack of consistency.

In the past (~5y ago) I was in favour of keeping it simple, but now I would more support a modular approach with these features:

• individual recipes in standalone files
  • could be JSON, YAML, React components
• a compilation step that outputs an HTML file like the current.

I'd be willing to do the dev work to achieve this, though would def want support with code reviews and discussion.

I'd like to hear from the other maintainers (and indeed, anyone else who wants to weigh in):

1. What do you think about how we should structure ffmprovisr going forward?
2. If we refactor to a different approach, do you have any thoughts about which tech to use?

cc @ablwr @kieranjol @privatezero @retokromer @ross-spencer

[retokromer]

Two brief thoughts:

• If we forgo the possibility of using this resource offline, then the proposed solution seems to me to be the best.
• The problem I saw then, and still see today with a multilingual version, is the maintenance. (Let's not forget that even the Spanish version is still incomplete, despite several attempts.)

Nevertheless, I support the idea of ​​taking this path.

[kfrn]

@retokromer, regarding this point:

• If we forgo the possibility of using this resource offline, then the proposed solution seems to me to be the best.

If the build step were to output an HTML file like the current one, would that be an appropriate mitigation?

I realise that you'd have to compile ahead of time though.

[retokromer]

@kfrn I would use pandoc, but that’s only because I’m used to this tool. And, probably, generate a PDF file rather than an HTML file.

[kfrn]

@retokromer I haven't used pandoc, but it indeed looks like a great tool!

[privatezero]

Hi @kfrn, I haven't had time to fully think this all through, but I agree that some of the underlying calculus has probably changed since the last time we all talked about this. I suppose I would be open to a restructuring of ffmprovisr to something beyond static html, provided we could do it in a way that still made it relatively accessible for people who aren't super tech savvy to contribute.

In terms of a tech to use, honestly I don't do a ton of web focused work these days so the only vaguely relevant tech I have used is jekyll (which I love because I like both markdown and Ruby), but beyond that I don't have any deep or insightful suggestions.

Also, +1 for pandoc being great!

[ross-spencer]

Hi @kfrn thanks for raising this again. I am in favor of separating things out, but it'd be great if a measure for success could be that it was still possible for someone to contribute "one thing" and then that gets incorporated into the whole. It gets harder to contribute if you add a recipe but also have to update an index manually somewhere.

In that regard then I guess finding the right build approach will be important both online and offline. Providing helpers (e.g. via justfile) for people offline will help reduce friction and there may be enough variability between us here to test builds on different operating systems. Given the state of GitHub at the moment, then maybe avoiding GitHub workflows may also be a consideration (or finding a workflow that's compatible across sites like GitHub + Codeberg).

I've referenced FFCommand_Engine and the previous reciples.txt file in old writing of mine as a great way to enable FFMProvisr as a CLI based API and given a flexible build system and definition of recipes there may be options to output multiple representations in a single file, e.g. user-friendly HTML representation in the body + microdata describing the recipe in the header which could be extracted by machine and turned into something like that (that might be a future iteration).

Just one additional consideration re: build/data, but I've had some success with browser side sqlite, e.g. 0xFFAE (in this case using Pyscript) so one option could be to compile recipes into a database and retrieve them, e.g. recipe by language from a database and display those based on what's selected in the UI. JSON/YAML/TOML may still prove a lighter (and more ergonomic) lift. Database storage would need to be a build step because it would be difficult to review otherwise. I am still ironing out another proof of concept for this.