search

ipfs-inactive / website

This repo has been replaced by https://github.com/ipfs/ipfs-website/
https://github.com/ipfs/ipfs-website/
MIT License
182 stars 128 forks source link

[DISCUSSION] Site replatform alignment #412

Closed jessicaschilling closed 3 years ago

jessicaschilling commented 3 years ago

Details in progress, but tldr: replatform existing site to VuePress in order to:

This is intended to be a "lift and shift" effort with minimal visual styling work.

Please contact @jessicaschilling with any questions in the meantime.

jessicaschilling commented 3 years ago

Two questions for @zebateira, @cwaring and @andyschwab to discuss before proceeding (Ze will lead the conversation):

  1. Is VuePress still the right choice of platform, in terms of both functionality and consistency with our other top-level sites at PL?
  2. Are we planning on deploying sites like the blog and main ipfs.io via Fleek going forward, rather than on our own cluster?
warpfork commented 3 years ago

Okay, sorry to jump in here, I'm definitely not the one owning this piece of work so my opinions won't count for much -- but, I've been wondering very similar questions lately as I look at some other sites, and wondering where to ask them, so forgive me for taking the opportunity here.

Some random and opinionated observations:

My takeaways from that are:

I'd love to listen in on whatever discussions come on these choices. I'll probably be doing some work soon that uses one of these families of tools, so I'd love to stay as aligned as possible.

jessicaschilling commented 3 years ago

All good points, @warpfork ... please watch this space, but a few thoughts:

andyschwab commented 3 years ago

Quick notes here:

To clarify, the new Filecoin site uses Hugo. I am, though, comforted to hear that @warpfork's experience with Hugo mirrors my own.

zebateira commented 3 years ago

Regarding the first question Is VuePress still the right choice of platform, in terms of both functionality and consistency with our other top-level sites at PL?, here is my evaluation:

Since the objective is to reduce context switching and overall consistency within our work, choosing a framework that can handle all types of use cases (main website, docs, blog, etc) is key.

Because of this, I also explored the possibility of creating one single website repo that would encompass all of the projects: IPFS, IPFS Docs, IPFS Blog, other IPFS misc websites - something like this would need to be thoroughly planned and performed overtime, but beneficial I believe. And the best starting point would be the ipfs.io website. (This is how drand was done using VuePress).

Note: big thanks to @cwaring for his initial research which inspired mine 🙏

Candidates

Note: considering the aim to reduce context switching, it felt natural to stick with vue frameworks - if using react is something we want to standardize, Gatsby would be my proposal. See here for a very detailed comparison table between Gatsby and others (including Hugo and Nuxt.js) - a lot of the metrics are not relevant for us here.

Categories to evaluate

Proposals

I excluded Gridsome considering its small ecosystem and lack of maturity - it's promising, but not quite there yet.

Option A - Nuxt.js

npms.io scores:

image

Option B: VuePress

npms.io scores:

image

Option C: Gatsby

npms.io scores:

image

Conclusion

I recommend both Nuxt.js and VuePress with a preference for Nuxt.js. I believe both Nuxt.js and VuePress would serve our use cases well, but Nuxt.js would be better. The reason for that is because although VuePress has been used successfully within PL, there are some caveats that steer me into thinking that Nuxt.js might be a better choice now: Maintenance & support, Configuration, Developer experience.

First, it is a bit concerning that they have so very few maintainers that they can't guarantee bug fixes in the current latest version 1 of VuePress because they are developing version 2. There is some hope though with 3 releases so far since December, but still, this is something to watch out for.

Secondly, even though in some use cases minimal configuration is good, it can cause some issues when we need something more custom. Doesn't mean VuePress can't do the job, it's just that it has not been optimised for those custom use cases and we might bump into roadblocks that cost a bit more time to go around even though you can accomplish the end result you needed. This might not be an issue for PL and IPFS specifically now or in the future, just something to keep in mind.

On a last note, I did find Nuxt.js's documentation to be easier to read and follow, and the API more intuitive.

Last thoughts

In the case of migrating all the IPFS websites into a single website repo, Nuxt.js would be more flexible to handle all the use cases than VuePress.

This is something we should evaluate on another issue, but migrating to a monolith for most of IPFS websites (at least main website, docs and blog) would be a huge win IMO. So if this is something we want to pursue or at least have it within arm's reach, Nuxt.js will be more helpful I believe.

React vs Vue

If this is something debatable, there would a lot to be gained from using Gatsby over Nuxt.js considering support and performance are better. Some points to take into consideration are:

jessicaschilling commented 3 years ago

Thank you, @zebateira -- this is extremely thoughtful, detailed analysis. Three followup questions:

  1. How easy is deployment of a Nuxt.js site over Fleek, since we've standardized on Fleek?
  2. How much custom work would need to be done in order to deploy a Nuxt.js site directly over IPFS, if Fleek isn't an option for some reason?
  3. What would the expected effort be to eventually migrate both the IPFS docs and IPFS blog including Forestry layer (both have a LOT of content) to Nuxt.js if we decided later to go the monolith route?
zebateira commented 3 years ago
  1. Should be as easy as VuePress. For two reasons: (1) there shouldn't be any blockers considering that Nuxt.js also supports static html generation just like VuePress and (2) the relative paths issues has been mitigated for any framework by using subdomains (correct me if I'm wrong here @andyschwab).
  2. Defering to @andyschwab: do you foresee any issues that could arise from using different frameworks that output static html?
  3. Good question: it shouldn't take longer than a replatform effort for each, the amount of content in them is not something that will affect the effort proportionally.
johnnymatthews commented 3 years ago

This is excellent, thanks for diving into this @zebateira!

Maintenance and support: how active is the OSS project and what are its future plans Number of maintainers, sponsors and overall activity in the right direction for a sustainable long-term project.

This is something that concerns me about any framework we pick. Eventually, that framework will fall out of favour and/or maintainers will stop maintaining things. With that in mind: should we create our own framework/static-site generator?

Creating our own solution comes with a bunch of overheads and is highly-non-trivial, but also has two major benefits:

  1. We can add whatever features we need, and ignore the features we don't.
  2. It will always be maintained, assuming PL assigns a team to maintaining it.
jessicaschilling commented 3 years ago

@johnnymatthews That's a good point, but I fear that would push this work so far out of scope for accessibility as a near-term win that we'd have to shelve it entirely in order to be in line with the team's larger priorities. (We also know that we don't have the bandwidth to assigning a team to maintaining a custom platform.)

If we feel that writing our own platform is a must, and worth postponing any work on ipfs.io until then, we can do so. That's a decision beyond my role, though.

terichadbourne commented 3 years ago

Thanks @zebateira!

@johnnymatthews - I'd venture to push back a bit on your assumptions re benefits of building our own framework: 1 - My impression is that Nuxt.js is already modular in a way that would already allow us to pick and choose pieces we need to some extent (@zebateira could you confirm?) 2 - Based on staffing and prioritization constraints that I've seen typically here, I think we need the solution that would work best if we don't have consistent internal maintenance. I think we're more likely to succeed with a set-it-and-forget it platform.

terichadbourne commented 3 years ago

@zebateira I don't want to position our work in a way that makes it only serviceable by a specific agency (should we continue to learn on agency support over internal development), but I'm curious to know whether Moxy -- and other agencies if you feel you have a broader sense of the market -- would be any better armed with boilerplates for one platform you've suggested versus the other.

zebateira commented 3 years ago

re building our own framework

Even most agencies don't build their own framework because of the points all of you raised.

However, to answer your question

This is something that concerns me about any framework we pick. Eventually, that framework will fall out of favour and/or maintainers will stop maintaining things.

We do two things to try to mitigate that issue as much as possible: choose a framework wisely and build a boilerplate.

To choose a framework, we choose one that (A) is based on ambitious and clear goals that align with our own and (B) has a lot of maintenance support and sponsors (usually B follows A, and even contribute in B by contributing to it or sponsor it). Those are usually the main factors that indicate very good user adoption and continuous long-term support.

Of course there's always a small possibility that it could all go to bust - but even if it does, since there is a huge community that also depend on the framework, there will always be a clean path out. That's why I believe sponsors are also important, because where there is investment, you will get some return back.

zebateira commented 3 years ago

@zebateira I don't want to position our work in a way that makes it only serviceable by a specific agency (should we continue to learn on agency support over internal development), but I'm curious to know whether Moxy -- and other agencies if you feel you have a broader sense of the market -- would be any better armed with boilerplates for one platform you've suggested versus the other.

Good question. At MOXY we have our own boilerplate Next.js with MOXY. And I'm sure we could find good Nuxt.js boilerplates, but I believe PL would benefit greatly by building its own boilerplate instead since the goals of the boilerplate would not always sync with PL's goals. I didn't propose this yet because I still don't understand what are all the requirements that could fit into a boilerplate that PL could reuse across projects. I do have some ideas, but would need some time to create a plan since it involves input from several parties.

atopal commented 3 years ago

Hmm... one of the assumptions we are making here is that the framwork needs to be vue, but considering that we want to use as much as possible off the shelf software, it might make sense to focus more on the ecosystem. Gatsby for example has a massive ecosystem and is based on react.

zebateira commented 3 years ago

Hmm... one of the assumptions we are making here is that the framwork needs to be vue, but considering that we want to use as much as possible off the shelf software, it might make sense to focus more on the ecosystem. Gatsby for example has a massive ecosystem and is based on react.

Ah yes, there is another reason why I felt that we should use Vue. I'm sorry I didn't make it clear here:

Note: considering the aim to reduce context switching, it felt natural to stick with vue frameworks - if using react is something we want to standardize, Gatsby would be my proposal.

I wanted to add that the fact that Vue seems to be the preferred one at PL, is also something to consider. But like I said, if using Vue is not a requirement, I would make the switch to React with Gatsby considering the huge support and performance we'd get from it.

I'll make this more clear by adding a third option C.

cwaring commented 3 years ago

Thanks for picking up the evaluation, @zebateira. I agree this is the right way to approach this in 2021, Vuepress has proven to be a great choice given the original deliverable of our documentation platform with other constraints at the time - even though we stretched it to deliver https://protocol.ai/ and https://drand.love/ it is not a one-size fits all solution and as noted the limitations start to show for large website structures.

That said what @jessicaschilling has rightly pointed out the selection here should remain simple and accessible for the primary fact that we want to make sure our websites are easy to maintain, performant and quick to deploy for all teams.

🪄 A few important points we should consider:

Currently most of our web properties are built around Vue which I personally believe is more accessible than React for junior developers and simple applications, plus you get true single file components and we can reuse prior work from our current projects. So I would suggest we explore this path before a refactor to React etc.

A primary goal for the framework/technology to get out of the way so that our web properties are more maintainable and accessible, which will empower people to contribute confidently. There is always a balance of power and flexibility that comes with frameworks, and I believe some constraints are a benefit – which is one of the attributing factors to why the simplicity of Vuepress has been successful so far.

💫 Where we are now:

It was always a consideration that if we were to out-grow Vuepress that there should be a relatively simple path forward to port the content to a new framework. The trade-off is that we would need to rebuild and maintain the markdown pipeline and plugins that Vuepress provides out of the box, for this we need to evaluate the development necessary and whether the other requirements above can also be met without too much effort.

Until now I have maintained most of these properties and helped others to self-serve along the way, so if we are to go further down the customisation route we will require more developer effort to support everything. I would first determine what we want to achieve and then how we are going to support it for long-term success with appropriate ownership. The resulting technology is just a tool to help us reach that goal and keep shipping 🚀

zebateira commented 3 years ago

@cwaring thank you for the input 🙏

To refer the points you mentioned:

All websites should be static first and not require a server for running.

All good here 👍 all the options I proposed support this.

The output should be IPFS friendly, loadable via a gateway url (https://gateway.ipfs.io/ipfs/CID) and root domain (https://website.io).

Most likely the Achilles tendon here, but it is something we were expecting to happen that we would need to help and fix - just as @andyschwab said, it will help the community as well to make more tech compatible with the IPFS gateway.

The content tree should be markdown only and use front matter for configuration (this keeps everything portable and accessible).

All good here as well 👍

The build process should be fast, unobtrusive and the output should be SEO friendly and performant.

All good here as well 👍

Additional notes

It was always a consideration that if we were to out-grow Vuepress that there should be a relatively simple path forward to port the content to a new framework.

That is a very good point, and I agree that moving to Nuxt.js is a more straight forward path 👍

jessicaschilling commented 3 years ago

Is it correct to state that at this point, alignment seems to be congealing around using nuxt for replatforming ipfs.io?

If this is indeed correct: Since this replatforming doesn't involve much content at all, proposing that we use this as an opportunity to iterate on a boilerplate for nuxt + tailwind + Fleek and/or direct IPFS deployment. Would appreciate a weigh-in from everyone who's commented so far, particularly since we need to get a decision to Agency Undone for the ecosystem directory as well.

orvn commented 3 years ago

If this is indeed correct: Since this replatforming doesn't involve much content at all, proposing that we use this as an opportunity to iterate on a boilerplate for nuxt + tailwind + Fleek and/or direct IPFS deployment. Would appreciate a weigh-in from everyone who's commented so far, particularly since we need to get a decision to Agency Undone for the ecosystem directory as well. @jessicaschilling

I've written a comment here that compares Nuxt and VuePress (in the context of the IPFS interactive ecosystem) here: Issue 410.

Quote of my comment for easy reference and discussion in this issue:

Platform Nuances

  • Nuxt is to Vue as Next is to React:

    • It's the server-side rendered version of Vue, ensuring that it serves up bot and SEO-friendly content (which Vue doesn't do on its own, since it's a frontend-only Single Page Application that heavily manipulates the DOM)
    • Nuxt is a large, well-known, and popular project that most Vue developers either actively use or have come across

  • VuePress is similar in implementation: pages are compiled into a static site and served server-side

    • However VuePress Is mostly designed for content-based projects, like blogs or documentation
    • VuePress use cases are built around having a substantial amount of text, and using Vue to provide additional functionality around interactivity (custom components, routing, etc.)

Distinctions

Since the IPFS ecosystem is interactive, a great deal of the functionality isn't really content or page-based. Instead it's state-based (i.e., what's the state of a series of filters and other user inputs).

The benefits of using Nuxt are:

  • Nuxt will run in static mode: so it will compile into a static site
  • Therefore it will still be usable on IPFS, and via Fleek
  • The application can be switched into a fully progressive web app, with a dynamic backend, without significant overhead (if there's ever a need for it in the future, I know that that's unlikely)
  • Nuxt will make the process of serving up endpoints for injecting the embedded container (CTA/summary view) easier
  • Content will still be editable via markdown; or json, in the case of structured data, and PRs can still be made to amend data
  • We could still integrate with Forestry at a later date, so provide more polished content management
  • We have used Nuxt for other PL projects before, so we can port some useful base functionality over to accelerate development

The VuePress docs themselves have a section about Nuxt, where they stipulate when it's better to use VuePress:

  • "Nuxt is capable of doing what VuePress does, but it’s designed for building applications. VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box."

In other words, while Nuxt has a static mode that's comparable, it behaves more like an application. VuePress is designed to behave like a content website.

cwaring commented 3 years ago

Thanks @orvn, great points and completely agree. I was writing this as your reply dropped in...

It's still a matter of different tools for different jobs in my view, they all have their merits and should be selected based on the primary goals in mind.

In the world of vue:

  1. Building an application -> nuxt, vite, vue-cli
  2. Building a cms or content heavy site aggregating multiple sources -> gridsome
  3. Building a documentation app or simple website -> vuepress

In the world of react:

  1. next, create-react-app
  2. gatsby
  3. docusaurus

We can create common ui by implementing tailwind, or equivalent atomic css framework - this helps with enforce some consistency and familiarity.

note: root and relative path IPFS support is only possible in vuepress & hugo when I last evaluated this, if this remains a hard requirement then our options are limited without significant custom development and investigation. Alternatively we accept that most modern web apps require a fixed root depth it opens up our possibilities. For instance Next.js is powering Slate, despite this limitation because it helps us achieve our goals. Trade-offs.

This is something we should evaluate on another issue, but migrating to a monolith for most of IPFS websites (at least main website, docs and blog) would be a huge win IMO. So if this is something we want to pursue or at least have it within arm's reach, Nuxt.js will be more helpful I believe. - @zebateira

From an end user perspective it is nice if the experience appears this way, however from a management and contribution perspective it is far easier to have separate independent repos that have their own issue queue and pr review process. For instance almost all the community activity goes on in the docs repo at the moment. So this should be considered if a decision is made to move in this direction.

orvn commented 3 years ago

Conclusion: I recommend both Nuxt.js and VuePress with a preference for Nuxt.js. I believe both Nuxt.js and VuePress would serve our use cases well, but Nuxt.js would be better. The reason for that is because although VuePress has been used successfully within PL, there are some caveats that steer me into thinking that Nuxt.js might be a better choice now: Maintenance & support, Configuration, Developer experience. @zebateira

Root and relative path IPFS support is only possible in vuepress & hugo when I last evaluated this, if this remains a hard requirement then our options are limited without significant custom development and investigation. Alternatively we accept that most modern web apps require a fixed root depth it opens up our possibilities. For instance Next.js is powering Slate, despite this limitation because it helps us achieve our goals. Trade-offs. @cwaring

Also to add to what @cwaring and @zebateira mentioned. We've actually successfully used Nuxt on a couple of PL projects, both in static mode on IPFS, and as a full PWA with some feature rich functionality that required more than what could be accomplished on the frontend alone.

jessicaschilling commented 3 years ago

Per sync meeting 16 March: Reassigning this issue to @atopal @cwaring @zebateira in order for them to make an executive decision on how we are to proceed. @atopal would prefer the org as a whole align on React. Acknowledging that work is blocked until a decision is made.

@atopal has acknowledged and approved that @orvn is researching possibility of root/subdomain support for nuxt, and that in order to keep Agency Undone work from being completely blocked, it may result that the ecosystem directory departs from eventual PL org standard.

warpfork commented 3 years ago

I apologize slinking away for a while as fireworks fly...

I love the roundups of considerations, especially cwaring's post here.

Big ups for things already looking widely agreed on:

There is at least one more consideration I'd like to throw into the ring that I haven't seen touched yet:

I also wanna comment that one of the constraints mentioned earlier seems like a nice-to-have to me:

Finally, I wanna put this on offer: some notes I scraped together myself recently while looking into static site gen tools: https://gist.github.com/warpfork/79edc135e049f1c43142a7e14c8beb31

All in all... Thanks for all the consideration ya'll are doing on this, and thanks everyone for sharing these notes on the thinking!

atopal commented 3 years ago

We've just had a chat where we decided to move forward with nuxt on an experimental basis. We'll use that experiment to determine the possibility of subdomain support for nuxt.

cwaring commented 3 years ago

Thanks everyone for the great contributions! @zebateira excited to see what you come up with 🥳

jessicaschilling commented 3 years ago

Thanks all for keeping pushing forward on this 😊 @zebateira, @orvn at Agency Undone is currently working on a PoC for subdomain support for the ecosystem directory. May I ask you both to touch base so you're not duplicating work?

zebateira commented 3 years ago

@jessicaschilling sounds good 👍

cwaring commented 3 years ago

@zebateira also I forgot to mention the nuxt content module which may be worth trying out as our markdown/content pipeline, it looks super powerful and could save a lot of custom dev time.

orvn commented 3 years ago

Nuxt IPFS Module Update

Some additional information to close the loop here: