Hey,
I was thinking to make a proper react site for Joplin. The current site is Nice but the folder structure and the Docs are a complete mess(no offense). We can make a new Site with a proper folder structure and a proper pattern so it can be easy to maintain and scale.
The Tech Stack I was thinking to use : -
Next.js (A React Framework used by Tailwind, React new docs(in beta), Hulu). I think it is best for static sites, SEO, and a lot of good stuff.
Typescript for the language
MDX for Documentation
Jest and Cypress for testing
Deploy on Vercel (Next.js is created by them).
For UI we can use Either tailwind or Chakra-UI (or maybe both together)
The homepage, News UI will be the same.
A new UI for Docs will be created and some more standard functions like search and better navigation.
Download App option in the NavBar.
I love to use Plugins with Joplin, We can add a new page for plugins with all the plugins in some order(most download, recommended ones, etc) same as the App but for searching in the site.
I need to do a lot of research on this so better start early. It can be a good GSOC project for this summer. I am making the Documentation UI in Figma which I can share in a few days if we agree to this new site idea.
Waiting for the community response. Constructive criticisms are most welcome.
Next.js Will also build a static site. I checked the Joplin-docs, the UI looks great, It is great from a user point of view, but from a developer's, don't you think React.js is mostly used and better to maintain by the community. Big projects like ChakraUI, React Docs,Tailwind uses Next.js
For the Lib use
MDX allows to use React Components in the markdown file.
Jest and Cypress are just for testing the codebase.
I want to use Next.js because it contains some cool features like
Image Optimization for faster site load.
Internationalization(Built-in Domain & Subdomain Routing
and Automatic Language detection.) If in future we use it
Static site generation as you said
File-system Routing
and lots of more stuff.
Won't this potentially raise the barrier of entry for people wanting to make useful documentation contributions? Trying to help improve documentation was where I got started with this community and I think seeing functional code within the docs would definitely have driven me away due to perceived complexity and being scared of breaking something - Markdown is easy to write and preview no matter what you have installed locally.
I don't think using 1 or 2 React Components in the middle of a normal markdown file makes it hard for the user to contribute (Cos rest everything will be same as a normal markdown) and also it's a feature we could use not compulsory to use. (like if we want to add a graph, some sort of React card component in our documentation, a Custom card component for showing contributors section, etc)
I don't think using 1 or 2 React Components in the middle of a normal markdown file makes it hard for the user to contribute
Yes. Yes, it is. It adds complexity to something that is, at the base, text. It adds complexity to how that page has to be rendered. What, exactly, needs interactivity in the docs? What pressing need is solved by React et al?
No offense but I can hardly see the advantages or value of building a new site. Current website is working fine, and it seems that there isn't any problem that exists in current site that is solved by the new site. It would be great and more convincing if you could list some concrete examples that is causing some issues now and will be improved upon in your proposed version.
Actually, I thought then the whole Joplin codebase is on Javascript and Typescript(React.js), So in the site, we could also use React.
The main function I want to add is a Search bar for the documentation(using algolia or from scratch) and to make a standard folder structure for the markdown files.
/docs/index.md = Getting Started Guide (Home page of the Docs)
/docs/applications = Folder for the [desktop.md, mobile.md,terminal.md,web-clipper.md]
Same goes with the others. This will be easy to contribute and find pages.
The main docs make contain a lot of stuff we should also divide it into small parts. eg-
A separate Contributors section
Localization Page
Plugins List page
Also as the 3rd project of the idealist of GSOC suggest the refactoring of the current documentation, that's why I was thinking to make a new site from scratch with react this time. I saw many big and small Projects using next.js with MDX in their documentation so I recommended it.
Having a search bar and sidebar would indeed be useful but as it's been mentioned in other threads we'll keep static Markdown files that are converted to HTML because that makes everything easier - editing the files, building the website, hosting it.
In any case, the difficulty here is mostly how to re-organise the documentation, for example, how to split the large README we have at the moment, which sections to create, how to handle the fact that there are multiple apps with both shared and unique functionalities, etc.
Then comes the technical part of updating the build scripts and CI to support this, but that comes later.
OK, I leave that idea for now. But just to quote Next.js with Vercel hosting will never really cost you anything(It also deploy directly with GitHub and Vercel provide you a CI (like every code push it will build a preview link and if anything breaks it won't affect the production build) & also you get Analytics for your site) and you can also export it to static HTML and host it on your GitHub pages with the same functionalities.
I am working on the documentation structure to re-organize it in a better way. I'll create a topic vise tree for that and share it soon here.
Just as a note, there already exists many project that builds beautiful documentation sites that supports static Markdown file as input, search bar and side bar, just name a few:
May I kindly remind you there is also joplin-docs which aims to offer a better documentation center. The website is up and running. Why not give a try ? Anyone can add/edit content or create/suggest a new structure
First step is to define the new doc structure we want as Laurent remind us several times (the topic Refactor project documentation may be the appropriate place for this)
However I don't see why not start gathering the doc. IMHO the temporary structure we put in place (whatever it is.) will be more effective and user-friendly than actual solution And even if this is not the final solution at least we start building a better doc center.
The point is to have the doc in md format, editable by the community. This to have one reference point once for all. For me docs and website can live separably. That's good to keep flexibility and allow those 2 projects to evolve easily.
So I want to ask if we are making it a dynamic site under joplinapp.org/plugins, shouldn't it be easy to make a react site, so we can add plugin route and many more thing if needed in future since the whole codebase is written in React so everyone is comfortable with it and won't have any issue in the development process.
And if are not using react then how should we approach the project. Cos rest of the site is the HTML render of the markdown file.
