Docusaurus migration

[akarsh1995]

Why Docusaurus:

• Docusaurus is meant for the docs in particular
• Night mode out of the box.
• Broken internal links are checked during the build.
• Algolia search can be integrated.
• Auto rss.xml generation.
• Docs versioning feature

For more visit: Docusaurus 2021

Have a quick look of the temporary hosted website @ Netlify

Few things to consider now while writing markdowns

• Admonitions

:::{note/tip/info/caution/danger}

{text}

:::

• Footnotes

  [^1]
  [^1]: nth reference

• When inside a blog markdown and want to reference any blog entry.

  you can use relative path [What's new in Axum 0.5 ]: 2022-03-whats-new-in-axum-0-5

  But when want to reference any tutorial doc, use [spawning]: /tutorial/spawning instead of just [spawning]: spawning.

• Styling html tags method has changed in the markdown

  use <div style={{ textAlign: "right" }}>&mdash; David Pedersen (<a href="https://github.com/davidpdrsn">@davidpdrsn</a>)</div> instead of <div style="text-align:right">&mdash; David Pedersen (<a href="https://github.com/davidpdrsn">@davidpdrsn</a>)</div>

Fixes : #544, #637

[tobz]

@akarsh1995 Wowee! This is a big PR. :)

Firstly, we really appreciate this contribution as better docs are something we love, and ultimately users love. Given the size of the PR, though, I'm curious if there's anything you could talk about that you fixed in the course of migrating to Docusaurus.

It'd be good to understand if this fixed real problems that existed versus simply changes over to a framework that's technically better on paper.

[tobz]

Also, similarly: as pointed out in Discord, it looks like the site is rendering slightly differently now. To wit, the header bar has different padding/width, font sizes are different in some cases, the component scroll section in the middle has different font colors on the left-side navigation, etc.

Is this something you're still working on bringing up to parity?

[akarsh1995]

@akarsh1995 Wowee! This is a big PR. :)

Firstly, we really appreciate this contribution as better docs are something we love, and ultimately users love. Given the size of the PR, though, I'm curious if there's anything you could talk about that you fixed in the course of migrating to Docusaurus.

It'd be good to understand if this fixed real problems that existed versus simply changes over to a framework that's technically better on paper.

Hi @tobz,

I totally appreciate and it's worth comparing the current implementation and the docusaurus one. Here's what I felt and what drove me to this implementation.

I was using the sea orm in my project. And I could easily navigate through the documentation. Things were proper in a place like

• Search bar. The kind of search bar I feel at home.
• Dark UI, etc.

Does the question come why tokio-docs should change as per my choice preference?

Many projects in the rust ecosystem use it. It'd be great to have a consistent ecosystem. It reduces friction.

• Tauri
• Yew
• Sea-QL
• Solana

• Polkadot

While Learning tokio, when I was sitting in front of the screen switching back and forth from the dark editor to the light theme for more than an hour straight, it was an annoying developer experience.

I saw that issue #544 had not been fixed since 30 January 2021.

Being Tokio, the mother of all async libs, I expected the docs to provide a par-level experience.

I could have just changed the color scheme right in the existing codebase to contribute. Even though I had invested my little time in it, I thought it would just solve one of the current problems.

Some other accessibility issues that I faced

• Copying the code blocks from the tutorial in a single click.
• Searching the documentation and blog.
• No filename is mentioned @top of the code blocks. I had to look out for the filename in the text back and forth. refer: codeblock title.

Some other issues commonly exist, if not now, then possibly in the future.

• Versioned docs
• Docs internationalization
• Sharing the permalink of any header. Rust's vision 2024: Help users help each other

I could have fixed all features manually, one by one. But why reinvent the wheel?

That's where comes docusaurus.

I want to empower new contributors to contribute. Docusaurus has the existing documentation to let the new contributors contribute to the docs and features for a learner to begin.

I believe it'd help us attain consistency in evolving rust ecosystem. I'm sure our user base is going to explode in the future. Consider this PR as a base to make docs evolution way easier.

[akarsh1995]

Also, similarly: as pointed out in Discord, it looks like the site is rendering slightly differently now. To wit, the header bar has different padding/width, font sizes are different in some cases, the component scroll section in the middle has different font colors on the left-side navigation, etc.

Is this something you're still working on bringing up to parity?

For that matter, I'll make the landing page exactly look alike.

[tobz]

Thanks. I appreciate the comments about your experience moving between the documentation of different projects and noticing how Tokio felt "off" compared to other projects. Between that, and the potential future benefits -- versioning, internationalization, etc -- it seems like this is a solid upgrade to the website. 👍🏻

I, or someone else from the team, will be looking out for when you get the landing page up to parity, and then I think we can take a deeper look across the site. I suspect that there won't be much deep review of the framework itself -- it's just a means to an end, after all -- but the real concern is making sure the UX and design doesn't regress.

[akarsh1995]

Thanks. I appreciate the comments about your experience moving between the documentation of different projects and noticing how Tokio felt "off" compared to other projects. Between that, and the potential future benefits -- versioning, internationalization, etc -- it seems like this is a solid upgrade to the website. 👍🏻

I, or someone else from the team, will be looking out for when you get the landing page up to parity, and then I think we can take a deeper look across the site. I suspect that there won't be much deep review of the framework itself -- it's just a means to an end, after all -- but the real concern is making sure the UX and design doesn't regress.

@tobz, I've reflected upon your previous comment and made the changes accordingly.

I have made the landing page changes keeping in mind that the UI doesn't regress.

One major thing you might notice is the tokio logo in the footer. I've taken references from React Native and docusaurus default logo position. It looks great, so I've kept it in the center.

Please dive into the learn and blog page for further review. It's more framework specific.

[tobz]

@akarsh1995 Nice. It's definitely looking closer, visually, to the existing website. 👍🏻

After looking into the learn and blog pages, one discrepancy I noticed is that while the current blog page has the right-hand navigation controls for each section of the current blog post, the new design does not. I did notice, however, that the learn page on the new design still has the right-hand navigation controls.

Is this something not supported in the blog or was removing it simply an oversight?

[akarsh1995]

@akarsh1995 Nice. It's definitely looking closer, visually, to the existing website. 👍🏻

After looking into the learn and blog pages, one discrepancy I noticed is that while the current blog page has the right-hand navigation controls for each section of the current blog post, the new design does not. I did notice, however, that the learn page on the new design still has the right-hand navigation controls.

Is this something not supported in the blog or was removing it simply an oversight?

Thanks for the insightful feedback @tobz.

The page we land on clicking the blog link: /blog

whereas the article page is: /blog/2022-03-whats-new-in-axum-0-5

If you look for the specific article inside the blog, you'll get to see the relevant navigation controls.

To make the blog page self explanatory and more accessible. I'm about to take the following steps:

• Truncate the blog entries' summary.
• Increase the number of entries on the blog page.

[akarsh1995]

@akarsh1995 Nice. It's definitely looking closer, visually, to the existing website. 👍🏻 After looking into the learn and blog pages, one discrepancy I noticed is that while the current blog page has the right-hand navigation controls for each section of the current blog post, the new design does not. I did notice, however, that the learn page on the new design still has the right-hand navigation controls. Is this something not supported in the blog or was removing it simply an oversight?

Thanks for the insightful feedback @tobz.

The page we land on clicking the blog link: /blog

whereas the article page is: /blog/2022-03-whats-new-in-axum-0-5

If you look for the specific article inside the blog, you'll get to see the relevant navigation controls.

To make the blog page self explanatory and more accessible. I'm about to take the following steps:

• Truncate the blog entries' summary.
• Increase the number of entries on the blog page.

@tobz, The blog landing page is the first blog entry as seen on the live website. You may proceed with the further review.

[akarsh1995]

@tobz, Any update on this?

[tobz]

@akarsh1995 Where we're at is that this PR would need to match the current website design almost exactly to be considered for merging. There's a strong desire to not lose the work that was put into the current design.

I apologize for the different tone originally, as I wasn't expecting there to be opposition to the PR given the numerous benefits it brings... but I wanted to be up front with you here. If it's even possible to make the Docusaurus framework match the current design, and you're willing to put in the additional time to do so, we can very likely merge this PR.

No hard feelings if you simply want to close the PR, though.

[Darksonn]

We have decided to go with #688 instead.