what should we use to build the website?

[ghost]

so now that we've finally established a website team, we should discuss how to build the website! here's some suggestions:

• jekyll: integrates well with github pages (eliminating the need for hosting), has a flat file structure without any actual build code. i18n situation unclear, potentially incompatible with github pages
• metalsmith: tried and tested on the nodejs website, fairly antiquated, but also stable
• react: modern, but maybe too much for people that just want to add/translate content? jsx & co might be confusing to some. doesn't compile to static sites

if you have any other suggestions, please post them here! take into account things like translations, hosting and beginner-friendliness

[ghost]

/cc @ayojs/website!

[scotttrinh]

I agree that making the website a SPA is overkill at best and a hindrance to getting translation help, for sure. However, we could use react to create reusable components that the markdown content uses, when needed, just not sure how many times we'd need components that aren't already the stock HTML components. I don't think anything on the nodejs site is really interactive, right?

[nbarnes]

Jekyll is ruby-based. I'm professionally focused on Rails, so that's bully for me, but as ayo is a JS project, we might be better off not bringing in a language that many of the contributors might not know / be interested in.

react seems like way overkill.

metalsmith's i18n plugins all haven't been updated in two years or so, but maybe they're just stable? Dunno.

[scotttrinh]

@NoahDragon

I'd say this is appropriate place to put your vote in for Hexo. 😉

[Kataract]

Hugo may also be a good static site alternative, though I personally have not set up their i18n functionality and Go templates may be a problem point depending on everyone's experience.

Would it be worth it to spend some time figuring out things we need the site to do before choosing a base? That may help inform this decision a bit.

[eubenesa]

Would love to put my vote in for Gatsby, but I am down to give any help. :)

[scotttrinh]

From an outside-of-the-team's perspective, the two things I care about are accessibility and ease of contributing. I can't imagine the site needs any bells or whistles, just marketing, getting help/resources, and docs. Perhaps I'm overlooking a need or opportunity to improve on what node's website provides? Our focus on the humans of the project might highlight some interesting places where we might expand on what node is currently doing.

[mcataford]

We should probably first put together a rough outline of the content we want to feature and choose tools and processes around that.

I absolutely agree with @scotttrinh re:accessibility & ease-of-contributing. Depending on the kind of content and features we project implementing, we can probably pick the lightest / easiest to maintain structure and have a kick-ass site that shines by how easily people can use it to get to what they need. :)

[z0al]

I would vote for Gatsby too!

what type of contents do we have other than docs?

[joshclow]

I am most familiar with React, so selfishly that's where my vote would go, but if the consensus is that React introduces unnecessary barriers to contributing, then I'm absolutely willing to turn to other options.

[scotttrinh]

RE: React

To be clear, I am not saying we should "not choose React", as I don't see React being a framework for implementing a website, but a framework for writing composable components. The bulk of the website will likely be text and not interactive components, so I'm not sure how/where React would fit in.

Having said that, I would be happy if we reached for React (or Vue or Polymer or...) when/if some complex and/or interactive components were needed. Ultimately, using the existing Node website as a frame of reference, I don't see any reason to include a UI framework whatsoever, but I'm hoping someone might point out some ways in which we'd want to differ from what Node provides.

[joshclow]

Well, looking at Gatsby based on comments above, the flexibility in content management there does seem pretty attractive.
As for things we might do beyond what the Node site does, I don't want to make architectural decisions now that assume later work, but I think there's an opportunity to approach education/inclusion in a way that can reach visual learners and other folks not well supported by a wall-of-text model. But that's a very hand-wavy pie-in-the-sky thing that I've given exactly as much thought to as it took to write the post.

[ghost]

i'm imagining a very simple website (even simpler than the node.js website), more akin to the rust website, which is precisely why i don't see the need to include something as unintentionally confusing as react, and i'd prefer to stick to simple html or markdown pages and templates when possible. the docs are separately compiled anyways, and will likely not be directly hosted from this website (i think? @Qard)

[scotttrinh]

The nice thing about React is it is very lightweight and easy to integrate later, so I wouldn't worry too much about knowing ahead of time if we need it or not.

[scotttrinh]

Thanks @pup for bringing up the Rust website, I forgot how straightforward and simple it is, and would be a good amount of information to target for a first swing, I would think.

[abritinthebay]

Yeah, React is pretty trivial and easy - if our code is decoupled and modular it's super easy to add React at any point. Gatsby does look interesting.

I think the key is more info architecture at this point anyhow. The tech should come from the design and architecture of what/how we want to present it/goals.

[dentemple]

I work with React on a regular basis, but I do agree that it may not always be approachable for newcomers.

How about Vue.js? Some thoughts on its strength:

1. For small websites, it's very easy to follow what's going on under the hood

2. You can write component-based code, while still giving folks from an Angular background a way to ease themselves in

3. It's not tied to a major corporation

I only have a little bit of experience with Vue.js, though, so there may be issues here I'm not aware of.

Still, if we do stick with React, I definitely +1 Gatsby!

[scotttrinh]

I think my hesitation to pick a framework like React (or Vue or Angular or choo) is around the fact that we don't yet need any interaction, which is what I feel like these frameworks are meant to help with. For static sites with nary a form or user input in sight and no database/backend to speak of, I'm just not sure what we need a framework for.

[dentemple]

True. We definitely need to establish our priorities first.

From what I see, two major requirements for the website should be:

• As a user from <x> country, or as a person with <y> impairment, I would like to be able to easily consume the content

• As a FOSS maintainer, I would like to be able to help people maintain the files without asking for significant time investments from people

(As a stealth third requirement, I definitely agree that we should stick to the Javascript universe, so definitely no Ruby on Rails, as fun as it is to use.)

Thoughts on what else should have an impact on the decision here?

[scotttrinh]

I think the first requirement assumes we agree on what "the content" is, which I think we probably do, but is worth being explicit about it. I believe we've talked about the documentation being (technically) separate from the website, so with that in mind, it seems we want to supply the following information:

• Why does Ayo.js exist?
• How do I install Ayo.js?
• How can I get involved?
• Where do I ask questions?
• Who is Ayo.js?

Anyone disagree with any of these, or have any additional information that would be generally helpful outside of documentation?

[nbarnes]

I'm with @scotttrinh about needing a framework; i.e. we don't. It seems to me that ayojs' site is very nearly a perfect use-case for a static site generator like metalsmith or jekyll. I just looked at hexo and it seems nice as well.

[abritinthebay]

Well Gatsby is also a static site generator but yeah, we're getting ahead of ourselves:

What's the purpose, what's the user story? What's the intent, what's the general design idea of how to communicate?

Until we answer those the tech stack is not relevant.

[stefee]

I posted in discord so I'll post here too.

I think the best way of representing Ayo as a human-focused and inclusive project is by focusing on accessibility and clarity in the website design. My personal reference for accessible, clean design is the Tachyons website: http://tachyons.io.

I agree with those saying an app framework would be overkill here.

[NoahDragon]

I personally would recommend the Hexo https://hexo.io/ , it is a static website generator.

Not only because I'm the maintainer of Hexo, but also it provides the functionality we need, like i18n. It could be easily expanded and customized by plugins, themes, and scripts. Even the Vuejs official website is built upon it. https://vuejs.org/

Moreover, it is written in Javascript, and integrated with the Nodejs ecosystem, which I believe it could also easy to transfer to Ayo.js.

The Hexo website repo also demonstrates how it organizes the documentation and blogs. https://github.com/hexojs/site/tree/master/source/api
https://github.com/hexojs/site/tree/master/source/_posts

More samples could be found on https://github.com/vuejs/vuejs.org/tree/master/src/v2

Other website generators are also awesome, I just feel it may be easy for us to create a website quickly using Hexo.

[stefee]

I don't think anyone has posted this yet - there's a really nice comparison of static site gens here: https://www.staticgen.com/

I really like the look of Hexo! Unfortunately I don't think my opinion is of much value here; I'm relatively new to static site gens.

[moe-dizzle]

Do you all think it will be a good idea to come up with a list of must-have features first, such as i18 and accessibility? Then we can create the design and wireframes of the website. We can use that information to guide on what build/framework to use.

[abritinthebay]

That would absolutely be my preference.

[are]

There has been an effort on our Discord to use Loomio to reach a consensus and gather all possibilities, but it seems that not everyone from our team is present and/or active on Discord. Therefore I want to invite you all to our team on Loomio (as the other teams already considered using it).

We already finished one preliminary poll about what possible SSGs we would want to use, but it's definitely inconclusive, because we need all of you folks to take a part in it! Anyways - the results were strongly in favour of Hexo (6 votes), second (and the last) place had Metalsmith (3 votes).

We can also resolve other issues on Loomio, choose maintainers of the Loomio group and overally use it as an addition to Github - of course the main discussion should remain here, but for any decision-making process we can help ourselves with Loomio.

[z0al]

@are1000 Thanks, I had no idea about Loomio