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

docs: migrate to VitePress from VuePress #1578

Merged
merged 4 commits into from
Jun 18, 2023
Merged

Conversation

jthegedus
Copy link
Contributor

@jthegedus jthegedus commented Jun 14, 2023

Summary

Migrate to Vitepress v1 beta from Vuepress v2 beta.

Fixes: #1558

Details

Vuepress has a lot more dependencies, requires more configuration and the breaking changes during the Beta of v2 were becoming cumbersome to resolve. Dependabot got annoying quick.

Vitepress v1 was on the horizon, so I just waited until that hit a stable version to migrate the site across.

URLs should remain the same as the current deployed Vuepress, so existing links should continue to work.

Happily Vitepress also adds copy-to-clipboard buttons on code snippets which was requested recently in #1558

Vitepress also follows more modern design principles, eg:

  • the navigation is handled mostly through the left side-pane instead of dropdown menus in the top navbar
  • the headings for the current page are listed on the right-side, not nested on the left
  • search is much nicer and even local to the selected language

Vitepress does:

  • have a different API for importing other files
  • the default behaviour for line-numbers on code snippets is the inverse
  • it checks for broken or dead links within the site on build
    amongst many other useful things.

Other Information

We may wish to reconfigure the pages in future to take better advantage of the layout/navigation changes, but for today we're just doing a straight migration.

I did my best with the translations for minor wording changes to navigation items. Hopefully people will come and correct them in future.

Homepage comparison

NEW:
image

OLD:
image

Documentation page comparison

NEW:
image

OLD:
image

@jthegedus jthegedus requested a review from a team as a code owner June 14, 2023 16:19
@jthegedus
Copy link
Contributor Author

jthegedus commented Jun 14, 2023

@Stratus3D The idea here was to migrate to a more modern tool and then introduce a blog/ section so we can comment on the major changes released in 0.12.0.

Might be good to start posting in our documentation site about how we approach version pinning, reproducibility over ergonomics etc.

@jthegedus jthegedus changed the title docs: migrate to vitepress beta from vuepress docs: migrate to Vitepress from Vuepress Jun 14, 2023
@jthegedus jthegedus changed the title docs: migrate to Vitepress from Vuepress docs: migrate to VitePress from VuePress Jun 14, 2023
@jthegedus
Copy link
Contributor Author

Merging to test the deployment

@jthegedus jthegedus merged commit 5133819 into master Jun 18, 2023
@jthegedus jthegedus deleted the docs-migrate-to-vitepress branch June 18, 2023 06:24
@hyperupcall
Copy link
Contributor

It looks like this broke https://asdf-vm.com

@jthegedus
Copy link
Contributor Author

It looks like this broke asdf-vm.com

That may be because of the registrar migration for the domain. Please try again and share the result. I have had no issues testing on my devices.

@hyperupcall
Copy link
Contributor

We were hit by Google Domains too? 😅

Hopefully, its just an issue with my computer - this is what I get - after erasing cookies. I'll try again in several hours and update if anything has changed

image

@jthegedus
Copy link
Contributor Author

jthegedus commented Jun 18, 2023

We were hit by Google Domains too? sweat_smile

Yes, yes we were.

I see, I will investigate further.

EDIT:

Ah, this is probably it.


image

I'll continue to observe.

Not sure why clearing cache and cookies on my machine doesn't show this error 😕

@jthegedus
Copy link
Contributor Author

Not sure what the problem is with the TLS cert taking so long.

image

@jthegedus
Copy link
Contributor Author

Okay, should be good now.

@hyperupcall
Copy link
Contributor

Yup, works for me now 😅

@hyperupcall
Copy link
Contributor

TLS really be taking a day off today

@Stratus3D
Copy link
Member

Seems good to me. Thanks @jthegedus !

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.

Add copy to clipboard option on in the installation guide
3 participants