Hi guys,
I am thinking about how this Website Plugin should be implemented. I was using Vue.js and Nuxt to generate the website and Vuetify as the UI framework before, but I fail to consider how this project will be maintained since it seems that the majority of this community uses React more.
This project basically can be divided into 2 parts, building a website UI and generating static pages. Building website UI can be done with or without a JS framework such as React and Vue, and generating static pages can be done with existing generators or customized scripts.
Based on that I propose 3 other alternative solutions with their pros and cons in my head. Let me know which one you think is more suitable for this project.
Plan 1 React + Next
In this plan, React can be used to draw the UI and Next is for static pages.
Pros
- People are familiar with React in this community since Joplin is built on top of React
- Logic isolation with components
- Easy to generate pages in batch with Next function
getStaticProp() and getStaticPath()
Cons
- Too heavy for a static website?
Plan 2 No JS framework + Static Website Generator
UI will be written in HTML+CSS templates, and the generator will take care of static page generation.
Choice of the generator can be 11ty, PRPL or others.
Pros
- Easy to maintain (No JS framework knowledge required)
- Less work since the generator takes care of routing
Cons
- Can't think of any right now. It seems that this is a balance between plan 1 and 3.
Plan 3 Vanilla
Pros
- Even easier to maintain
- More customized
Cons
- Heavier workload since I'll need to write a generator from scratch
I must admit I haven't looked at how Joplin's web pages are currently generated or how the documentation is generated.
In my opinion, a complete custom development is the best to adapt but also the hardest to maintain in the long run.
Do all generators run as GitHub actions or how is the integration planned?
What is the approximate effort for the implementation?
I have little time this morning, because I have urgent business appointments. But I'll take some time this evening to continue the discussion.
Thank you for your time.
Currently, the Joplin website is generated by this script. This script calls a generator written by Laurent and it is fully customized.
Generators usually provide a command like nuxt generate for nuxt or npx @11ty/eleventy for 11ty. We can automate the process by setting up a GitHub action running this command when data updates. After the command was ran, it will generate the HTML files in a folder such as dist. And we can set up GitHub Pages from that folder.
If we choose to use existing generators, we only need to write the template and then fill in the data. If we decided to write a generator as the main website does, then we might need longer time.
I personally prefer to use an existing one since it's easier and it can be better maintained because most of the generators are well documented.
How much time do you have at the end to document the entire process in detail?
I'm wondering how quickly a stranger with not that much knowledge of it could maintain it (that heavily depends on the doc quality).
I‘ll make sure I'll leave enough time to make documents on how these things work. This process shouldn't be hard to understand once everything is settled.
An existing generator would indeed be better. How would you solve search when using such generator?
I can use my customized js to implement the search feature. We just need to embed the js into the template and use it to search through the plugin json.
Makes sense, thanks for clarifying. Also make sure the process is not tied to CI - it should be possible to run and test the whole thing locally
1 Like
@Retr0ve is there any input for our side needed to continue?
No need. I can choose the generator myself and start working on that. Thank you for your time! 
1 Like
Please let us know once you found a suitable generator
Okay. I've been looking for a generator for a while and I found astro did a really good job. It handles dynamic routing well, it's well documented, the community is active and the performance is better than most of the other generators.
I have done a quick check, it is an extremely young project tough widely used and very active. Maybe some research ensuring that it is a sustainable project could be helpful
It has many stars so it indeed seems to be popular.
Would it make sense to compare say 3 such tools and the pros and cons to find which one is best? For example "dynamic routing" - is that something that we need? Click a link, open an html page, it feels like we don't need anything more fancy, unless I'm missing something
To be clear I think we should set the requirements: the ideal case is simply a bunch static html pages that are deployed using GitHub Pages, no js, or dynamic routing, nothing fancy.
That's the ideal case - maybe we need more but in that case we should clearly identify those cases where more complexity is needed.
Dynamic routing is not something fancy, it is something we needed to generate pages in bunch. It mean we can use a dynamic data source to generate pages, such as the manifests.json in joplin/plugins. And almost all these generators support it, just some might call it by a different name.
These generators are pretty much the same. Astro compares itself to other popular generators here. It is not flawless but since we are looking for a simple and well-maintained generator, I think this is the one.
.
Dynamic routing is not something fancy, it is something we needed to generate pages in bunch
Thanks for clarifying, I thought it was routing using JS.
These generators are pretty much the same. Astro compares itself to other popular generators here. It is not flawless but since we are looking for a simple and well-maintained generator, I think this is the one.
Since it's a tool we're potentially going to use for many years to come I think it makes sense to spend 30 min to look at different options, and to make sure we choose the best one.
I think like laurent, the time should be used to compare the systems directly with each other.
Especially functions that we need or in the scope for use.
I don't think it's a good idea to just refer to a manufacturer's website and I wouldn't let that pass in an exam for my students or on a presentation from a staff.
Totally agree! Here is the list that I‘ve compared. (It only includes generators working on node.js and supported vanilla HTML template)
Astro
Pros
- Support dynamic routing
- Well documented
- Templating language is similar to JSX which means easy to learn
- Integration with modern CSS frameworks such as tailwind
- Partial hydration (not necessary but can improve performance)
Cons
- It is new and needs time for testing
Eleventy
Pros
- Support dynamic routing
- Support multiple template languages
- Well documented
Cons
- Hard to integrate with client-side js, we need to create asset build pipeline ourself. (We need this for search feature)
Static Site Boilerplate
Pros
- Lightweight, only contains the basics to generate a website
Cons
- No direct dynamic routing support, we need to implement that ourselves
- Document is limited
- Don't support layout reusage
You are right. I've done that minutes ago.
This is just for reference while I need time to collect all the information in detail. It's been hours is because its too late here and I have to wait to the next day to do all these and post it.