search

inventree / inventree-website

The official website for InvenTree - The Open Source Inventory System
https://inventree.org
Other
3 stars 10 forks source link

Experiment : Docusaurus #177

Closed SchrodingersGat closed 3 months ago

SchrodingersGat commented 10 months ago

Following on from this discussion

@wolflu05 mentioned that the gitea website would be a good starting point. They build using docusaurus which is a very nice modern framework.

As it turns out, it is also very easy to get started with.

This PR is a proposal to move to using Docusaurus for our website. Longer term, I would like to move our docs to this also. Perhaps re-combine them into a single site, for visual consistency and so we do not have to maintain two different sites.

That's longer term though. for now:

Immediate Goals

Future Goals

netlify[bot] commented 10 months ago

Deploy Preview for inventree-org-preview ready!

Name Link
Latest commit 0db5066acd5e9cba709ddd8cb0ad3814316418a8
Latest deploy log https://app.netlify.com/sites/inventree-org-preview/deploys/65aa537c1123c80009c729d2
Deploy Preview https://deploy-preview-177--inventree-org-preview.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

Lighthouse		 1 paths audited
Performance: 92 (🔴 down 7 from production)
Accessibility: 98 (🟢 up 4 from production)
Best Practices: 100 (no change from production)
SEO: 92 (🟢 up 17 from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

SchrodingersGat commented 10 months ago

Simple screenshot here (all the blog posts have been transferred now):

Screenshot 2023-11-23 at 9 48 16 pm
matmair commented 10 months ago

I was not aware there is a demand to change the website, thougt the discussions is about the docs, but why not; It would probably be good to not change the urls as we have a good ranking on google for our kewywords for the mayor sites by now. And we have InvenTree call the news endpoint so that also needs to stay the same.

matmair commented 10 months ago

I have no expertise or intrest in Docusaurus so not sure how/if the current approach of the website repo with yaml data files as data sources can be reprodced or needs to be rebuild.

SchrodingersGat commented 10 months ago

I have no expertise or intrest in Docusaurus so not sure how/if the current approach of the website repo with yaml data files as data sources can be reprodced or needs to be rebuild.

Same, had never heard of it until today. Currently playing around to see what is possible. Once the live preview is working it will make more sense I think

matmair commented 10 months ago

To me it seems to be a web focues docs framework - not sure how/if we can even get nice RSS and json files (for news, plugin repo) build. Have you checked if a conversion of the docs even works with this framework? Rebuilding the website is work but probably doable - I am really not sure if we can serve docs this way consistent with the current schema.

SchrodingersGat commented 10 months ago

Not sure 100% yet but the docs functionality looks very nice indeed.

As an example - https://docs.gitea.com

eeintech commented 10 months ago

Another example, Flet documentation is built with Docusaurus: https://flet.dev/docs/ I honestly enjoyed very much the look, the easy of navigation with the left and right side bars, and the search feature is really good.

I'm wondering: should InvenTree docs be moved on Docusaurus too?

SchrodingersGat commented 9 months ago

If we do this I'd like to move the docs too. It is a much simpler framework and visually much better.

I'd also like to consider moving the docs back in with the website. Not 100% sure how it would work with our current process. Let's discuss advantages / disadvantages.

One key point to consider is how we manage versions of the docs. Obviously we have to keep the old versions hosted on readthedocs.org but anything new would be inventree.org/docs

The process for releasing a new version would differ too. We can work that out I am sure.

I'd like to make some nice splash screen graphic for the website, and some small graphics to replace the default docusaurus ones. Perhaps even clean up the logo a bit. Anyone know a good graphic designer? I'd be willing to throw some funds at it.

I really like the landing page for openproject.org - although there is perhaps a bit too much information on the front page.

SchrodingersGat commented 9 months ago

For reference I would like to target the docs migration for our 1.0.0 release. A clean break from 0.x.y and we can use it as a milestone to change all the documentation to use the new user interface. All screenshots etc

SchrodingersGat commented 9 months ago

They also have a plugin for generating API docs which may be extremely useful to us

wolflu05 commented 9 months ago

I like the movement to docusaurus. Your draft looks really good for a starting point.

But I have a few things:

  1. as @matmair altedy said, we should not change the basic urls much, so the docs really should be available at docs.inventree.org
  2. why not clone the main repo for the docs deploy task and extract the docs from there?
  3. about docs versioning, doesn't docusaurus allows us that too?
SchrodingersGat commented 9 months ago

as @matmair altedy said, we should not change the basic urls much, so the docs really should be available at docs.inventree.org

Fair point, we can leave that to point to the new docs, and potentially leave old docs available at inventree.readthedocs.org

about docs versioning, doesn't docusaurus allows us that too?

Yes, this is what I plan on using. Their versioning support looks pretty good