Vuejs.org: Why not use Vue/Vue Router/Vue Server Renderer for vuejs.org documentation!

[Haeresis]

I'm not sure who is the correct people in charge of vuejs.org website (not content but development) and same for others documentation (Vuex, Vue Router, etc.) so I will address this message to @kazupon, @yyx990803, @chrisvfritz or @posva.

Current website

The current website is generated with Hexo that allows us to serve static page generation on GitHub Pages.

Vue, Vue Router and Vue Server Renderer allow us to serve behind each page the full content by HTTP response in the first place (with data-server-rendered="true") and let Vue hydrate that on client-side.

But this is actually not the case in official documentation, and I do not see any Vue + Vue Router script or data-server-rendered="true" in official documentation and that not allows users to navigate in a great reactive website SEO compliant without reloading between each page!

Future website?

1. That's should be a great thing if the current static website serves pages with dynamic navigation (without reloading page) and with SSR source generated. And it should be great if all of that continues to be on GitHub Pages.

2. That's should be a great thing if that should be built with actual Vue, Vue Router scripts and using data-server-rendered="true" in pages already generated.

A project like that is under construction? If not, let me do a proposition.

My proposition

1. Create a static website with statics pages generated using Vue Server Renderer as the engine to serve the full content by HTTP response in the first place when a page is requested from GitHub Pages. All pages will contain a data-server-rendered="true" part and the Vue + Vue Router scripts that allow them to be hydrated. When a user will navigate through the website, the navigation will be done by Vue Router. If users reload pages on a navigatied page, it's the HTTP response that serves the page, and after that, it's hydratation and Vue Router that serves futures pages... and so on.

2. Conserve the same HTML structure and the same CSS design as the current one. But navigation will not reload pages and later, great animation should be done.

3. Conserve same .md files to continue to write documentation in the same way.

4. Set all text in JSON file ready for localization to not « trap » content text into HTML files.

5. The gh-pages files will be generated by using only one command, exactly same has currently with hexo generate.

To do all that's things, I propose to use NodeAtlas that is a framework I created and I maintained. It can do all of what I already suggested. That will allow me to enhance the framework with your feedbacks for vuejs.org. Like Hexo, NodeAtlas is capable to generate static content for GitHub Pages and run a development server to test website. It is built with Express and can use Vue Server Renderer to generate static assets from .md files or run a website.

I already try to use dynamic page load from GitHub Pages with HTML History API and SEO content generated from .md files (without Vue, Vue Router and Vue Server Renderer currently) with NodeAtlas here :
— NodeAtlas (in fact, the NodeAtlas documentation run with NodeAtlas on GitHub Pages).

I already used NodeAtlas too with Vue, Vue Router and Vue Server Renderer to create SEO Node.js website with real-time exchange thanks to Socket.IO
— https://staging.orchard-id.fr/ (under development)
— https://staging.orchard-id.com/ (under development)

The next step is just to use node-atlas --generate feature to allow my current Vue website generate statics content for GitHub Pages (I know it's already possible but this project can be a good real case test for me).

By the way, NodeAtlas can create a documentation language per repository or all languages in same repository (like for Vue Router, Vuex, Vue Server Renderer, etc.). It's could be possible to use a more consistent website structure across all documentation in future.

Why do you think about a POC on a dedicated repository with some current part of documentation as a model and why not test that on the French website to kept user feedback?

My Resume

I really enjoy Vue community and it's why I drive the Vue French Community and translate resources in French. I also love JavaScript and it's why we decided to Orchard ID (my society) to promote Vue.js and NodeAtlas using it for our web app or web site development.

I'm currently a member of Vue Ecosystem:

What I have already done for Vue:
— Translate https://github.com/vuejs-fr/vuejs.org with team
— Translate https://github.com/vuejs-fr/vue-ssr-docs with team
— Review already translated https://github.com/vuejs-fr/vuex with team
— Translate https://github.com/vuejs-fr/vue-router with team
— Set up https://gitter.im/vuejs-fr/vue (old chat)
— Set up https://forum.vuejs.org/c/french

What I have currently done for Vue:
— Maintain up-to-date all documentation
— Review already translated https://github.com/nuxt/docs with team
— Translate https://github.com/vuejs-fr/vue-loader with team
— Answers question on old and new Chat
— Help to redirect user from old chat to Discord new one
— Answers question on French Forum

And why note maintained Vue new website documentation with your help soon!

Resume LinkedIn : https://www.linkedin.com/in/brunolesieur/?locale=en_US
Help Stackoverflow : https://stackoverflow.com/users/2412797/bruno-lesieur
Project GitHub : https://github.com/Haeresis/

It's will be an honor to help Vue community with a great reactive website for documentation.

Win-win

That can allow to Vue:
— to show with is own website what it can do.
— to have structure website and content text fully separate.
— to use a documentation generator for GitHub Pages using a tool maintained by a member of Vue ecosystem.
— to prepare a more consistent structure across all documentation thanks to the flexibility of NodeAtlas

That can allow to me:
— use your feedback and need for documentation to enhance NodeAtlas (and get some help to propose a correct english documentation...).
— use NodeAtlas for real used project to help him to be used.
— study Vue Server Renderer in depth to allow me to propose a better Vue integration in NodeAtlas.
— Participate in an important project for Vue in order to possibly become a core team member a day <3.

It's your turn!

What's your thoughs about all of this?

[chrisvfritz]

Turning the Vue docs into more of an app is definitely something we've considered in the past. It would allow us to do some much more interesting things, but when I've scoped it out, it simply hasn't been worth the time to develop compared to improving the quality of existing content and creating new resources.

That may change a few months from now though and in the meantime, I'd be open to a smaller-scale prototype for a specific part of the docs (e.g. the API, style guide, or cookbook), as an exercise to help us evaluate the feasibility of a rewrite.

Some others that might have thoughts/opinions on this: @pi0 @sdras @phanan @LinusBorg @Jinjiang

[pi0]

/cc @Atinux @alexchopin @egoist @alidcastano

[alidlorenzo]

Hi @Haeresis I agree it would be nice to see the Vue.js documentation to be made using tools in the Vue.js ecosystem.

I'm not familiar with NodeAtlas but the site would be easy to create with Nuxt.js, which is already a popular framework within the Vue community; and I created a content module, Nuxtent, to make the creation of content-heavy sites with Nuxt as easy as using Jekyll or any other static site generator.

With Nuxtent, once you add all the markdown files to /content directory, all you have to do is configure how the content data is compiled and request it within Nuxt's asyncData property. For example:

// configure content inside 'nuxtent.config.js'
module.exports = {
  content: {
    page: '/_guide',
    permalink: ':slug'
  }
}

// request content inside 'pages/_guide.vue'
export default {
  asyncData: async ({ app, route }) => ({
    lesson: app.$content('/').get(route.path)
  })
}

All the rest is Vue.js and Nuxt.js :)

Btw, with Nuxtent you can also automate the creation of naviation (all pages have their path and heading anchors included in their data) and use Vue components inside markdown files, which would make examples and demos easy to include in the documentation (see the Ency docs if you'd like a live example).

cc/ @medfreeman

[phanan]

Turning the Vue docs into more of an app is definitely something we've considered in the past.

Uh oh, and what was my opinion on this again? Can't recall 😄 . But now, in all honesty, I'd echo @chrisvfritz that such a big move would not really be worth the effort. I think we can all agree that the doc is as excellent as it is (as more than often praised by the community) because of the _content_, and not the technology behind it.

Talking about technologies though, the current doc is built with Hexo, which is dead simple to get running and as a result, contribute. Any other shiny setup (yes, including Vue+SSR) will just be at risk creating a barrier which prevents other community members from contributing to the project.

[sdras]

Thanks for the detailed proposal. I'll also echo @phanan and @chrisvfritz that current efforts are probably better spent on things the community can actively use on their own projects at this time, and content is king in this regard.

I can imagine a scenario like Chris said where a small proof of concept is built to assess the benefits and maintenance costs -with what @phanan mentioned in mind- that keeping the barrier to entry low for contribution is a key feature.

[Haeresis]

Thanks a lot for your feedbacks @chrisvfritz, @alidcastano, @phanan and @sdras. Thanks to others for your reactions. I will add information for precise my proposition.

For a prototype

So @chrisvfritz, you had been open to a smaller-scale prototype for a specific part of the docs, to have an estimation of effort.

Like you said. Waiting for others through. Just a word to say NodeAtlas is developt keeping in mind versatility and evolutivity so the initial structure could be really close of current one (to not spend a lot time before present something) and to be changed in the life of the project.

So @alidcastano, you have a counter-proposal which is to use Nuxt.js with Nuxtent because it's already supported by Nuxt Community.

You're right. Nuxt could be a good choice, your argument is tottaly relevant. I do not mention it because in my proposition I suggested to be the guy that spend the time to initiate the project and ensure, CSS, Vue Component, website content per language and documentation content per language was clearly separate and ready to allows any person to contribute. And in this configuration I imagine myself drive people with my preferred tool, and change/improve it with your feedback.

For continue with Hexo

So @phanan, you think to continue with Hexo is more simple for allows the community to help on documentation.

It's true. I did not have any difficulty to use Hexo and I never work with before. From my « user contributing » point of view, use documentation with Hexo means:

• Install project from Git, use npm install for init it and install Hexo for CLI usage.
• Find CSS in themes/vue/source/css, JS in themes/vue/source/js and Images in themes/vue/source/images if I want to change them,
• Find Site Content and HTML Structure in themes/vue/layout if I want to change them,
• Find Documentation Content in src/v2 and Documentation Image in src/images if I want to change them,
• Use hexo server and manually get to http://localhost:4000/ to see modifications in a development server.
• Use hexo generate to create all statics content ready for GitHub Pages.

From NodeAtlas point of Vue, that could be:

• Install project from Git, use npm install for init it and install NodeAtlas for CLI usage.
• Find CSS in assets/stylesheets, JS in assets/javascripts and Images in assets/media/images if I want to change them (https://github.com/Orchard-ID/Orchard-Website/tree/develop/assets),
• Find Site Content in languages/xx-xx (https://github.com/Orchard-ID/Orchard-Website/tree/develop/variations) and Vue Components in views/vue/layout (https://github.com/Orchard-ID/Orchard-Website/tree/develop/views) if I want to change them ,
• Find Documentation Content in src/v2 and Documentation Image in src/images if I want to change them,
• Use node-atlas --browse to open the browser on http://localhost:4000/ to see modifications in a development server.
• Use node-atlas --generate to create all statics content ready for GitHub Pages.

All previous changes no need restart server for development mode (same as Hexo). Thanks to assetsRelativePath, viewsRelativePath and variationsRelativePath options, the path to ressources could be themes/vue/source/css, themes/vue/source/js, themes/vue/source/images and themes/vue/layout (same as current) and why not themes/vue/content/xx-xx.

In production, the only cache: true options will set up all things to have performances similar to that (I do not use CDN):
— staging.orchard-id.fr => https://gtmetrix.com/reports/staging.orchard-id.fr/99qs4CGe (PageSpeed Score: A(98%) / YSlow Score: A(92%))
— staging.orchard-id.com => https://gtmetrix.com/reports/staging.orchard-id.com/Zfmo953l (PageSpeed Score: A(99%) / YSlow Score: A(91%))

Even if we use Vue, Vue Router and Vue Server Renderer, that is transparent for beginners. There is no webpack configurations, no gulp process, no extra tools to use. That should be a great sandbox for beginner want just touch some Vue component to enhance the website, or just change .md for change documentation same as currently.

And @sdras you think the effort should be better on think usable by the community.

Indeed ! The proposition does not suggest to keep a lot of time on already busy people in the community, I suggest to drive a lot of effort for the base project on my own with your supervision and feedback to improve myself and NodeAtlas with Vue.

More throughs

Others thoughts/opinions are welcome!

[phanan]

Well, to answer your section with my name in it, I'd argue that, at least the way I see it, the process with NodeAtlas isn't any simpler than that with Hexo. And development mode with Hexo doesn't require any server restart, either.

[Haeresis]

You are absolutely right @phanan for the server restart! What I want to say was « no needed server restart too, same has Hexo » because the goal of that part was to explain why the argument « more setup complexity, fewer contributions » from contributor point of Vue ( :D ) are not relevant in the case of my proposition. My bad. I will edit that point. Thanks.

[kazupon]

sorry, my mistake at mobile env 🙇

[sdras]

Hi All!
This has sat for more than a month now and it seems to me from review of the discussion that core team members feel this is a large use of resources for something that is lower priority for us currently. I'm going to close it out, with the compromise that we could revisit the concept a year or so, when we've made more headway with other things that are higher current priority for us.

I definitely do appreciate the time and effort you've put into this discussion, @Haeresis! I'm not against the idea but would like to focus our efforts on the content at the moment to provide the best experience possible for Vue developers that are trying to learn. Thank you!