Consider using Jekyll

[oferb]

The website looks really bad (hey, at least I'm honest) visually. We didn't invest in it, but, for sighted people it's good to have something that looks nice. We already have a visual design, but it needs to be implemented. It's just a design for a single page, the main landing page for the project.

[S0AndS0]

I'm currently using GitHub Pages along with Jekyll auto-builds on my Fork...

https://s0ands0.github.io/sensory-interface/

... at this time I think it's one of the better options for delivering consistent page layouts and design; it's not burdening this project with a bunch of redundant source code, is built-in with any GitHub repository, and thereby allows anyone to test Forks of this project without any developer-side setup.

[oferb]

Interesting. So if I'm a contributor to the project, how do I view my changes? Do I need a developer-side setup if I'm working on the main project and not a fork?

[S0AndS0]

So long as one doesn't mind public pushing, then the methods I'm using are easier from a Fork, in which case there's no need for setting servers up locally. While a bit involved to initialize everything for fork based development, it's something that's trivial to script something for.

If instead fully autonomous development is wanted, i.e. completely separate from GitHub, I've already written a set of scripts for configuring a Git user able to compile Jekyll based static sites.

From what I've gathered about multi-dev projects, it's often a good idea to use the main/source repository for merging with forks considered stable.

[oferb]

Right now when we work on the project, we can view local changes.

If we would make this change - that means to view the local changes, we need to either:

• Push them to a fork
• Install Jekyll

If that's the case, then I think that's a drawback of Jekyll that's not worth it for our current 3 static pages.

[S0AndS0]

That pushing to a Fork is even an option is one reason why I'd suggest choosing Jekyll. The way I figure is having more pages that test each feature would be made easier by having some form of site builder, because there's less copy/paste of boiler-plate stuff.

At this time, indeed there's only three pages, so I suppose know that it's an option when consistency of visual design is wanted.

[oferb]

Ok, so for now I'm closing this and we can revive it when we have enough pages that consistency becomes a problem. I renamed it to "Consider using Jekyll" and will open another issue with the visual design, so new users don't need to read the whole issue.

[S0AndS0]

I am reopening this Issue because there are now quite a few more pages, because discussion of having page components such as header and footer elements loaded via JavaScript has been brought-up within Issue #107, and because I read that @mohammad-suliman has been semi-manually transpiling MarkDown files into HTML.

So I've put sometime into Jekyll compatibility at S0AndS0/sensory-interface:gh-pages, because utilizing Jekyll will save time by fully automating the process of building static files for this project. And I believe utilizing Jekyll for building site files will make maintaining significantly easier, while also making the process of translating content to various languages much quicker for contributors.

A draft/demo is now live via GitHub Pages and while there are a few nits that I'm still picking at (mostly styling stuff), currently it's in a state that this proposal can be seriously reviewed by the whole team of Contributors. So I'm asking for feedback from everyone involved in this project, ie. @oferb, @mohammad-suliman, @wwwshayronen, @BitanTomer, because these changes will effect everyone working on this project; hopefully in a positive way.

Brief outline is that files within the _layouts directory are how pages will be rendered, and files within the _includes directory are included within layouts (eg. header.html corresponds to a header element's content). This hierarchy keeps each component organized and simple to reuse. Site content can be written in MarkDown or HTML files, or really any file type so long as it starts with FrontMatter configurations.

• Example 1: the main index.html page uses the layout from _layouts/home.html which builds /sensory-interface/, and this is accomplished via layout: home configuration at the top of the index.html file.

• Example 2: the public/_braille/index.en.md MarkDown file builds to /sensory-interface/braille/index-en/ page, and the public/_braille/index.he.md file is built into /sensory-interface/braille/index-he/.

Side note, the output path names probably will change if this proposal becomes a non-draft but hopefully everyone is following how this type of organization will facilitate more languages to be added, while also making the process of maintenance much simpler than it currently is.

Overall this proposal shouldn't adversely effect development process or make things more difficult (in fact for those translating content this proposal makes things much easier), because Jekyll can be added to the package.json file as a development dependency and a new run command such as npm run jekyll-build could be inserted. Meaning that hosting outside of the GitHub Pages ecosystem, or even pre-compiling much like what's done with TypeScript is totally possible.

Please review the purposed changes, and respond with questions, suggestions, and/or concerns, so that we can have an open discussion on how best to simplify the process of maintaining so many pages.

[oferb]

@S0AndS0, as discussed here and in private chat (again and again), we're not using static site builders in this project. I also don't want us to spend time on discussions about this, as it takes away time from other more high priority tasks.

I encourage you to focus your time and energy in one of the ~30 issues we currently have and try to tackle them.

Therefore, I am closing this issue again. I hope you understand.

[S0AndS0]

Is this a team effort? I ask because the CONTRIBUTING.md file uses words like "we", eg...

"We value any input, and welcome any discussions on adding new things"...

... and closing this issue before everyone that be apart of this project is allowed to discuss this proposal runs counter to the team guidelines that we've agreed to.

As stated above this is addressing one of those open Issues, #107 to be precise.

And to reiterate my preferences on private chat, I much rather have the whole team be allowed to guide this project.

[oferb]

We value your input @S0AndS0, but opinions may differ. Please respect that.

Please see this comment about simplicity: https://github.com/hasadna/sensory-interface/blob/master/CONTRIBUTING.md#very-important-point-about-simplicity

For that reason, will not be using static site builders for this project.

Please allow me to close this issue.

[S0AndS0]

Part of this proposal's aim is for simplicity, both in the here-and-now and in the future. It is far simpler for page content to be automatically transpiled, it is less prone to errors, and far easier to make site wide changes too.

For example, having shared header and footer elements (files) that are automatically inserted above and below page content, completely removes maintenance costs for syncing changes to every effected page, and reduces the chance that changes are not being applied to every page.

There are trade-offs for sure, eg...

• much like TypeScript adds an additional step before results but also mitigates things like type bugs, so too will building site pages mitigate issues such as layout synchronization and linking issues.

• much like TypeScript will refuse to compile if it detects bugs, a good site transpiler will refuse to build if certain errors are encountered.

Instead of closing this issue I'll encourage that the team as a whole be allowed to have an open discussion on if this site builder is a good fit, or if another page transpiler should be chosen instead. Currently this project is growing such that having this discussion is worthwhile.

---

For those that are unfamiliar with Jekyll, the first two goals of that project are (in their own words)...

Simple

No more databases, comment moderation, or pesky updates to install—just your content.

... and...

Static

Markdown, Liquid, HTML & CSS go in. Static sites come out ready for deployment.

... GitHub Pages supports this out of the box, so compiling source Markdown to HTML is fully automated in most cases, and local testing/private hosting setup generally a matter of adding the NPM Jekyll package as a developer dependency.

[oferb]

Our html components solution addresses those concerns and is simpler and more suited for our current use case.

I understand you may think differently, and that's fine. I'm also not arguing against Jekyll in general. For this project, right now, IMHO, it's not the best fit.

I prefer not to have a detailed pro-against discussion either as that takes time and effort. Some opinions are also personal opinions, there is not "one right way".

[S0AndS0]

Is there a Markdown to HTML tranpiler written for NPM? If so that would be very exciting, because at this time I'm only aware of the pseudo code within the zip branch, and while I'll agree that the home-brew HTML components option addresses some of these concerns, it does not address others; four for example...

• how does it simplify Markdown to HTML transpiling?

• how does it handle relative and absolute URLs for loading assets and linking to other pages within this project?

• when error is introduced where does it fail, ie. do we get a compiler error or are clients left to sift through console.log/console.error messages?

• is there a functioning demo available to compare against the proposed solutions that are available?

---

Thanks for sharing your opinions! I'll encourage you to share your concerns here too.

If we agreed on everything that'd be very dull. I appreciate that we can discuss our differing; opinions on what is a good fit for this project, and approaches for solving these issues. And because this is a team effort I'll also reiterate...

I'll encourage that the team as a whole be allowed to have an open discussion on if this site builder is a good fit, or if another page transpiler should be chosen instead.

Every individual has their own strengths, through combining'em I believe this project can better fit the needs of clients.