Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate framework to VitePress #29

Merged
merged 21 commits into from
Dec 16, 2023
Merged

Migrate framework to VitePress #29

merged 21 commits into from
Dec 16, 2023

Conversation

legoandmars
Copy link
Contributor

@legoandmars legoandmars commented Dec 13, 2023

There's a few things about docsify that have been personally bothering me and (IMO) are hampering the wiki a bit. There's some details in #12 and #26.

Basically:

  • SEO is not great, and we're only limited to the default page for SEO and embeds
  • Docsify isn't super modern, and these problems aren't fixable without migrating frameworks
  • Adding new things (like search) is going to be significantly more complicated than it should be using Docsify

This PR converts the wiki to use VitePress, a similar framework that also uses .md files
There were minimal markdown-changes that had to be made, I simply

  • Added description/navigation metadata to pages
  • Moved from old warning/infobox system (! >) to vitepress's formatting (::: warning)

This will make embeds look significantly better, and help the site a LOT on google rankings, hopefully getting the wiki recommended instead of random outdated articles

Here's a preview of how the new styling looks:
firefox_mnP3rMsOLn

Embeds also look significantly better now, here's before and after (notice how each linked page will now actually show proper page-specific metadata)

firefox_1hcvVwStwH

This also adds the following features:

  • Search box to easily find specific pages
  • "Edit this page" button at the bottom of each page that links to a convenient GitHub editor
  • New beginners guide page

@legoandmars
Copy link
Contributor Author

legoandmars commented Dec 13, 2023

This PR is feature complete except for:

  • Live Thunderstore version system
  • Translation
  • automatic CI deployment

all of which I will be added to this PR shortly

if you'd like to preview the new wiki locally run npm i then npm run docs:dev

@legoandmars
Copy link
Contributor Author

I would love any specific thoughts on this @MaxWasUnavailable @Xilophor. I have tried to make the transition as smooth as possible: hosting and writing new articles should be essentially identical

Contributing should also be more directly accessible with the "Edit this page" button. I'd like to write up a contributing guide like bsmg.wiki has at some point

@MaxWasUnavailable
Copy link
Contributor

MaxWasUnavailable commented Dec 14, 2023

Adding new things (like search) is going to be significantly more complicated than it should be using Docsify

Docsify already has a search, which seems to work fine. Could you elaborate?

image

@MaxWasUnavailable
Copy link
Contributor

This PR is feature complete except for:

* Live Thunderstore version system

* Translation

* automatic CI deployment

all of which I will be added to this PR shortly

if you'd like to preview the new wiki locally run npm i then npm run docs:dev

What do you mean by Live Thunderstore version system?

@Xilophor
Copy link
Contributor

After quickly going through a local preview, it looks and feels significantly better than the docsify version. I'm happy that this process allows better SEO. From the article writing side, I'm glad that it's virtually identical.

What do you mean by Live Thunderstore version system?

This, no?
image

@legoandmars
Copy link
Contributor Author

Adding new things (like search) is going to be significantly more complicated than it should be using Docsify

Docsify already has a search, which seems to work fine. Could you elaborate?

Ah yeah I dropped a word there, I specifically meant Algolia search so we can have more relevant search than just "search the exact phrase"

What docsify has works alright, but I do think having something that supports synonyms/more complicated queries would be nice, especially as the site grows

@legoandmars
Copy link
Contributor Author

legoandmars commented Dec 14, 2023

What do you mean by Live Thunderstore version system?

The r2modman page runs a query to thunderstore to get the latest r2modman version, I just need to reimplement it for the new framework

Honestly we might want to remove this at some point, it's fairly minor and I don't want to accidentally burden thunderstore with massive amounts of traffic - i'll probably make an issue later

@Xilophor
Copy link
Contributor

Adding new things (like search) is going to be significantly more complicated than it should be using Docsify

Docsify already has a search, which seems to work fine. Could you elaborate?

Docsify did have a search function, although it doesn't seem great.
image

Looking at the exact same search in the new one, it gives a much better preview (if enabled).
image

Ah yeah I dropped a word there, I specifically meant Algolia search so we can have more relevant search than just "search the exact phrase"

Looking at a potential search, it does seem to better support/sort based on complicated searches that don't exactly match the content. Example search: how do I load the network object into the scene

Docsify
image

VitePress
image

@legoandmars
Copy link
Contributor Author

Right now it's just using vitepress's (solid) local search, but once it's deployed and had some time to simmer I'll try to set it up with Algolia, which should be even better

@Xilophor
Copy link
Contributor

Right now it's just using vitepress's (solid) local search, but once it's deployed and had some time to simmer I'll try to set it up with Algolia, which should be even better

If that's just the local search, I can't wait to see what Algolia looks like. Any timeline on when you plan to add that as a PR/to this PR?

@legoandmars
Copy link
Contributor Author

If that's just the local search, I can't wait to see what Algolia looks like. Any timeline on when you plan to add that as a PR/to this PR?

One of the people I consulted with about frameworks specifically said it's a bit of a process to set up, so it'll probably be a week or two

@legoandmars
Copy link
Contributor Author

The r2modman page runs a query to thunderstore to get the latest r2modman version, I just need to reimplement it for the new framework

Honestly we might want to remove this at some point, it's fairly minor and I don't want to accidentally burden thunderstore with massive amounts of traffic - i'll probably make an issue later

I've just removed this for now. It's neat but I'm worried it's not helping with the thunderstore downtime

I'll look into doing it on build time in a separate PR

@legoandmars
Copy link
Contributor Author

Translation also needs to be fixed in a separate PR because I think the only way to get crowdin to register the new changes is pulling them into main

This was referenced Dec 15, 2023
@MaxWasUnavailable
Copy link
Contributor

Looks superb! Great work @legoandmars

@legoandmars legoandmars merged commit eed46e8 into main Dec 16, 2023
2 checks passed
@legoandmars legoandmars deleted the vitepress-migration branch December 19, 2023 20:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants