[DISCUSSION] Site replatform alignment

[jessicaschilling]

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

• Match existing deploy processes for blog, docs, etc
• Facilitate ease of future improvements: interactive ecosystem diagram, content enhancement, etc

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]

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]

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:

• I had heard VuePress is the consistency choice around here;
• but that doesn't actually seem entirely true (I haven't been tracking actively, but I think I saw some things from the research org are Hugo powered, and possibly some other things from PM land?);
• I've tried VuePress and it drives me mildly nuts -- it's spectacularly slow. The output is also... something. (I'll share notes on this privately if anyone's interested, but spoiler, it's downright ranty.)
• I've also tried Hugo and it drives me mildly nuts -- it's fast, at least. The output is reasonable. My biggest complaint is that configuring it the first time is a wild journey of themes and overrides and pagekinds and much of it makes little sense to me, even after the fifth time I've made a Hugo site. I feel I've gotten the best results when I rip most of Hugo's fancier features out again, which is not my favorite vibe from a tool.

My takeaways from that are:

• Everyone defacto agrees markdown should be the main input format, and static html should be the output.
• Other than that it seems perhaps somewhat up for grabs?

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]

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

• If we operate under the assumption that our long-term maintainers for all Filecoin and IPFS sites (at minimum) will be the same folks, it makes sense to avoid context-switching between languages for those maintainers. Filecoin and IPFS docs — which are going to be the most frequently touched of these sites as a whole — are in VuePress, hence the original inclination toward VuePress. @zebateira is checking into this because this might not be a correct assumption. 😊
• We may have less need to make top-level ipfs.io MD-driven, as it's intended to be a fairly evergreen site (or, when changes are made, more likely to involve visual design changes as well), but that's a good point to keep in mind.

[andyschwab]

Quick notes here:

• I would love to see Fleek continue to be used, both to free up bandwidth for the infra team and to support the ecosystem
• I think most of the legacy sites used Hugo, since Hugo (if I understand the history) was the first static site building tool that enabled pure relative-path builds and thus full IPFS compatibility. Having more build tools (VuePress, Vue, etc.) that can create IPFS-friendly content is a win to me, so I'd argue gently for letting teams use what they are most productive with.

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

[zebateira]

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

• VuePress: Vue-powered Static Site Generator
  • More focused on docs.
  • It is a really powerful tool when you only need to create a docs site (the default theme is the main reason why vue libraries docs sites all look the same: vue-meta, vue-router, vue-loader, etc). And it seems to blend really well inside a project repo within the docs folder.
  • It can also be used for any website type, but you need to go around the defaults and customise it a bit
• Nuxt.js: The Intuitive Vue Framework
  • More oriented for customisation.
  • Vue framework for any type of website, but minimal configuration is required to setup specific use cases (blog, docs, etc).
  • Equivalent of Next.js
• Gridsome: A Jamstack framework for Vue.js
  • Performance-focused static generator
  • Vue framework for any type of website, but minimal configuration is required to setup specific use cases (blog, docs, etc).
  • Equivalent of Gatsby

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

• Features: are all the requirements easily addressable with this framework (including plugins)
  • localization, SEO, Search, markdown support (code highlighting, toc, etc), etc
• Developer experience: what is it like to use the framework and customize it?
  • Documentation quality, ease of use of API
• 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
• Initial configuration effort: how much effort to bootstrap and configure a project?

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:

• Features: Nuxt.js has a wide variety of features available if we include the featured modules that more than cover all our requirements.
• Developer experience: API and Documentation are very easy to use and navigate.
• Maintenance and support: it's very actively maintained with a lot of sponsors with very specific long-term goals
• Initial configuration effort: because some features come from modules, you will need to setup some things when bootstrapping a project

Option B: VuePress

npms.io scores:

• Features: VuePress has a wide variety of features available if we include the featured plugins that more than cover all our requirements.
• Developer experience: API and Documentation are easy to use and navigate.
• Maintenance & support: v1 is not actively maintained now due to the lack of maintainers so they are focused on developing v2 only with very specific long-term goals.
• Initial configuration effort: VuePress is very easy to setup with minimal configuration.

Option C: Gatsby

npms.io scores:

• Features: Gatsby has a wide variety of features available if we include the featured plugins that more than cover all our requirements. Of the three, Gatsby has the most ones.
• Developer experience: API and Documentation are very easy to use and navigate.
• Maintenance & support: it's very actively maintained with a lot of sponsors with very specific long-term goals
• Initial configuration effort: Gatsby is very easy to setup with minimal configuration.

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.

• Example for Nuxt.js: https://nuxtjs.org/ (main, docs, blog, examples, resources, courses)
• Example for VuePress: drand.love

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:

• Vue seems to be preferred over React at PL
• In a transition period, using Nuxt.js with Vue would allow us a smoother transition.

[jessicaschilling]

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]

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]

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]

@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]

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]

@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]

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]

@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]

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]

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]

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:

• All websites should be static first and not require a server for running.
• The output should be IPFS friendly, loadable via a gateway url (https://gateway.ipfs.io/ipfs/CID) and root domain (https://website.io).
• The content tree should be markdown only and use front matter for configuration (this keeps everything portable and accessible).
• UI components should conform to a common atomic css framework for consistency and cross-application reuse/maintenance (I recommend https://tailwindcss.com/).
• The build process should be fast, unobtrusive and the output should be SEO friendly and performant.

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]

@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]

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

• Still Vue, so consistent at least at a language level with other IPFS sites - as well as a growing number of PL sites as a whole
• A more appropriate (?) choice than VuePress for a smaller "showcase" site like ipfs.io
• Aligns with the nuxt-based solution proposed by Agency Undone (@orvn @D3AS8A) for the interactive ecosystem directory being built under https://github.com/ipfs/website/issues/410

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]

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]

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]

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.

• The Filecoin Network Status page network.filecoin.io is a static Nuxt site deployed on Fleek. It has been maintained collaboratively by both us and internal PL team members (who have provided both content updates and code refactoring)
• Slingshot 1.0 was the competition dashboard we used for the Filecoin Slingshot competition. It was a Nuxt static site at the time, and a legacy version is still visible here
• Slingshot was later extended into an app with full backend, as we needed more robust functionality (registration/authentication, user data, account management, server side temporal/cron jobs, etc.). This transition wasn't too bad, because Nuxt allows the switch from a static app to a SSR app running on Node/Express relatively easily

[jessicaschilling]

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]

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:

• static output 💯 💯 💯
• markdown and frontmatter as input: yes yes
• build should be fast and unobtrusive: yes heckity yes
• super glad all of these are no-contest :)

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

• Please consider the "shippedness" of whatever tools we favor.
  • What does that mean? Roughly: "can I use this by downloading a single, coherent binary/package, and immediately use it?" If yes, then it's "well shipped".
  • If the instructions to use it say "first, on platform X, do apt shoop whoop -- that's not well shipped.
  • If I have to install the go toolchain and build something with it -- that's not well shipped.
  • If there's an invocation of npm anywhere in sight -- that's not well shipped.
  • Why do I care about this? I want to be able to install the tool easily and develop content on my machine; and I want to be confident it's not going to have a halflife between breakage events. If something is "well shipped", there's one version number to care about, and that means I can probably fairly easily install the tool on my own machine. If something isn't well-shipped, it means I'm stuck experiencing an entire package management toolchain in order to get a result, and that means A) anyone not used to working with that system is now out of their comfort zone, and B) when multiple independently versioned components are in play and the upstream doesn't make pre-tested bundled, the odds that things are going to break over time are very high.
  • I'm not trying to pick on anyone's package manager -- the key is, if I am experiencing a package manager, then that means I'm not experiencing a pre-tested bundle of things that are known to work together.
  • For the user story of "I want to put together a documentation site" (not a super fancy site I want to put a whole team on developing the shine of, or even that I want to have a full time active maintainer of at all)... simplicity of setup is major 🔑 .

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

• "gateway friendly" URL emission (e.g. works under /ipfs/{CID}) is nice to have, but it's not clear to me how strongly we should consider that a strict requirement.
  • With the existence of CID subdomains, the criticality of this seems to go significantly down.
    • (I realize this is a relatively new thing, but... still, it's awesome and we should feel free to use it, as far as I can figure.)
  • The actual goal state here seems somewhat quixotic to me. If the content is all generated with relative links... this still only works for the original "root" CID, no? If one jumped a few directories into the content, then took the CID of that and dropped the directories stepped over from the path... it's possible that that subdirectory will render mostly correctly... but anything that links back "up" will still be broken, right? Maybe this isn't a problem; I'm just thinking through this outloud, and wondering how valuable this is.

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

• This gist happens to contain a pretty different selection than what was examined upthread. VuePress might be the only overlap! Whee, so many options. 🙃
• The extra special spicy comments about VuePress's output are in there. 🤷
• I will be no means say anyone has to take any of those notes into account. I figure I just might as well share them since it's something I already drafted up for personal tracking on the topic.

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]

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]

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

[jessicaschilling]

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]

@jessicaschilling sounds good 👍

[cwaring]

@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]

Nuxt IPFS Module Update

Some additional information to close the loop here:

• We created a Nuxt IPFS module available here

  • It extends Nuxt (while running in target: 'static' mode) to support IPFS gateway paths, in addition to the primary path it was originally compiled for
  • All resources load relative to the base (preserving gateway.ipfs.io/ipfs/Q...)
  • A demo of an app running is linked in this issue

• Nuxt is a lot more feature rich than Vuepress, and it required numerous considerations on how to replace the base of different kinds of assets (a detailed write up will be available in the repo readme later)

  • The benefit is that extending a static site to a full application is relatively easy, by switching nuxt's mode (to ssr or universal), which reduces overhead when an app's requirements can no longer be satisfied by a static site

• Interestingly, the nuxt/nuxt.js repository had an issue/8229 specifically about IPFS Gateway support a few months ago

  • Nuxt's team actually implemented this and closed this issue (and several other similar ones)
  • But they misunderstood how IPFS works, so this feature isn't available for in static mode
  • We'll open an issue with them about this, and given the recent high activity in the repo, it seems like theey could implement this functionality natively in nuxt in static mode