Discussion: refactoring index.html into individual recipes to be loaded as one

[ross-spencer]

I chatted with @kfrn and @ablwr about the potential of this, and it seem's that there's a nice discussion to be had about ways to make the index.html of ffmprovisr could be refactored to be a little less unwieldy.

I've started a refactor which I'll re-skin and add new recipes for, for another project. The refactor is currently available in gh-pages here to demonstrate that it works:

• https://github.com/exponential-decay/wikidigi

I'll keep this branch around though in case it remains useful.

The index.html now links to recipes with a snipped along the lines of:

      <!-- Basic rewrap command -->
      <label class="recipe" for="basic-rewrap">Basic rewrap command</label>
      <input type="checkbox" id="basic-rewrap">
      <div w3-include-html="recipes/basic_rewrap_command.htm" class="hiding"></div> 

This makes it a bit easier to add a new page and add information to index.html but creates a new problem, cross-origin links require a web-server to work, as per:

• https://stackoverflow.com/questions/10752055/cross-origin-requests-are-only-supported-for-http-error-when-loading-a-local/21608670#21608670

But the idea of a refactor so that index.html remains manageable, and user friendly, seems like it might be a good one.

Other (very briefly) discussed potential options might be:

• React.js
• Creating a Jekyll site

But this ticket serves as a location to discuss those idea and whatever options might be available.

It seems a pretty big catch is how do we change this in a way that maintains the benefits of a single .htm which offers lots of advantages such as demos offline, and no need to contributors to build the source and play it back via web server.

[ablwr]

To publicly summarize the ideas I spilled out to Ross earlier (many of which he has already done):

I'd be into changing it up so that recipes are easier to submit, similar to how AVAA functions, and have the recipes themselves as sparse, individual YAML files. Then contributors don't have to be people who know (or are willing to dig into) HTML to contribute. And the files can be concatenated, looped through, and compiled as one big index.html.

I prefer YAML because it's totally human-readable, but JSON is a possibility.

The downside to this is the static index.html is easier to use and test, or can be downloaded and immediately used without any kind of server setup or compilation. So it's very user-friendly from this perspective, the offline-usage perspective.

I'm a sucker for Jekyll but am trying to avoid it these days due to it not being very newbie-friendly for those who do not already have Ruby installed on their machines. Likewise, similar feelings with React, which I just kinda dislike overall and in general (although know it'd be super easy to do the looping procedure).

Interested in hearing others thoughts on this, especially people who rarely or sparsely contribute, or do not have any-or-much experience with web dev and do have experience with ffmpeg.

[kfrn]

I definitely think the index.html is pretty unwieldy now, and actually in the last while I was already thinking about restructuring it somehow, perhaps React.js-ifying it. So thanks for opening the discussion, Ross!

Cut and pasting some of my contributions to the discussion we had in Twitter:

I like the idea of rewriting it in React (or Jekyll, etc), but there are three big advantages of the status quo:

1. Low barrier to entry - probably as low as any project like this can be

   • I weight this pretty highly. Even if you don't know anything about HTML, it's still quite easy to make a direct contribution using the template.

2. No compilation step! Very beneficial for those who might want to contribute but aren't webdev-knowledgeable.

   • Like Ashley and Ross said, it's as simple as opening index.html in a browser .

3. Offline access is a key use-case for ffmprovisr, and right now the structure makes this very easy

I'd happily convert the site to React, or some other tech (I'm just much more familiar with React than Jekyll etc) if people want to go in that direction. If we are going to split out recipes and have a compile step, then a Markdown-based approach is probably easiest for users.

Curious to hear what everyone thinks!

Edit - posted at the same time as you, Ashley! So we share many thoughts :)

[ablwr]

Another thing I mentioned offline is that it would truly be nice for ffmprovisr to be able to handle other systems, like someone on Twitter mentioning the wish for one for Exiftool, and I would like one for ImageMagick and scaling up the system in this way would allow it to scale outward as well through some sort of tagging system that would allow the generation and reveal of everything associated with one type, ffmpeg, exiftool, etc., because it wouldn't be limited to one big index.html.

But again, like @kfrn says, I also weight the low barrier to entry to be very high too.

[privatezero]

Yeah...I personally like Jekyll etc, but I think that might be seriously raising the barrier to entry for lots of potential contributors.

Speaking as someone who was able to propose some recipes to ffmprovisr before I knew much about web-dev (and who still isn't SUPER strong in that area) being able to just open index.html copy an existing recipe to use as a template and then preview in a browser made it much less daunting to get involved! I think it might be a shame to lose this, even in the interest of a slicker nicer tool.

[ablwr]

I also just realized that ffmprovisr could grow laterally with "exiftool.html" and "imagemagick.html" living adjacent but in the same codebase.

[privatezero]

+1 to that! I was thinking kind of the same thing - could have ffmprovisr grow to support other tools by having separate pages instead of intermixing.

[kfrn]

Intriguing idea! CSS and JS all reusable, cross-linking between the HTML files - that could work quite nicely.

[retokromer]

Cf. as well #211.

[EG-tech]

I don't have much to add here but I am extremely interested in the discussion to apply to Cable Bible as well!! I just added a couple new modules this weekend and was thinking how unwieldy the index.html is and was wondering if that's why no one else has ever added/edited a module 🤣 😢

Spitballing because I am still barely familiar with tools like React/Jekyll - is it possible to generate a giant static HTML like the current homepages from the dynamic HTML compiled by Jekyll/React? i.e. basically create two versions in the repo, one dynamic that's friendly for the web and for adding contributions, and then a static, self-reliant ("uncompressed") version from that which is great for offline use

[ablwr]

I can definitely see the advantage of moving to an individual-page style for the Cable Bible because loading all of the images can get a bit unwieldy -- although that's a value to ffmprovisr as well, as the gifs grow and get bigger -- but especially for the Cable Bible since images are more core to the site itself.

For React and Jekyll, it is easy to do both! Again, A/VAA can be referenced -- there's a page that rounds up all the images and also pages dedicated to tagging. It can also loop up all of them in a simple way.

I want to mention that something I brought up in #211 (thanks for linking @retokromer!) is not wanting to break any links, so some care should be taken if choosing something else to not lose the existing links/refs.

[EG-tech]

yes, great point - that just made me remember/realize that the whole pinouts aspect of Cable Bible is super broken because of internal linking that I didn't carry over correctly from the last restructure 🙄

well +1 to adding recipes via more human-readable YAML/JSON/markdown snippet files in any case, and expansion to exiftool/imagemagick. (sox? @privatezero ?)

So if both versions could be offered for offline release/use, the main downside to Jekyll/React is @privatezero 's point of not being able to easily preview a potential contribution? (without setting up a Ruby/JS dev environment). That would be a shame to lose, but my feeling would be that the advantage of an even more simplified template system (here's what sample markdown files look like, just plug in your script's info) would outweigh that.

[ablwr]

I'm going to make a new issue just about what tools are a good fit for expansion since that's slightly different to the scope of this one.

[ablwr]

I am thinking that the conclusion seems to be we will leave ffmprovisr as one big bulky page, for the sake of simplicity, offline use, convincing new archivists to give github a try, etc...?

[kfrn]

Hey, thanks for the nudge, Ashley. That does seem to be where we landed.
I'm cool with it if people want to take another approach, but I won't push for it. (Partly for pragmatic reasons, and partly because I prob can't help in the next little while - heavy schedule at the moment).

[ablwr]

This is definitely worth maybe doing or bringing up in the future though and it sounds like none of us are strongly opposed! I am gonna close this issue in the meantime though. @ross-spencer thanks so much for thinking this through though, and best of luck with your similar project (hope to see it in action soon)!

[kfrn]

Just rereading, and I'm wondering where we stand on this nowadays?

Personally, my position hasn't really changed. :D As much as my developer brain likes the idea of a Jekyll-style static site, or a nifty Vue app, I think that the current approach's low barrier to entry (and offline accessibility, etc) is a huge plus.
Plus, not having a compilation step - if you're not experienced with that kind of thing, getting that going can be a real faff.

[privatezero]

My thoughts are pretty much the same as well - current approach has a lot going for it that outweighs any technical streamlining that could be done.

[ablwr]

Yeah I feel the same. The compilation step is crucial to me, being able to just open index.html locally and see the change immediately.

I have thought about creating a form that will generate the right HTML, so people can focus on the commands part and not the minutiae of checking for quotation marks and IDs, as a way to make it easier. And there's plenty we can focus on in terms of streamlining the HTML.

[kfrn]

Cheers @privatezero & @ablwr!
@ablwr, that's an intriguing idea. It sounds like that wouldn't really affect the current structure (I'm imagining something that spits out HTML and then the user cut-and-pastes that into index.html - correct me if I'm wrong), so maybe we could take that up in a new issue?

It looks like we have a pretty clear consensus, so I'll close this issue for now. If we want to discuss it further, we can reopen. :)