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

Docusaurus migration #652

Closed
wants to merge 67 commits into from
Closed

Docusaurus migration #652

wants to merge 67 commits into from

Conversation

akarsh1995
Copy link

@akarsh1995 akarsh1995 commented Apr 5, 2022

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
Copy link
Member

tobz commented Apr 6, 2022

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
Copy link
Author

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.

@Darksonn Darksonn requested a review from tobz April 10, 2022 08:06
@tobz
Copy link
Member

tobz commented Apr 13, 2022

@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
Copy link
Author

akarsh1995 commented Apr 13, 2022

@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
Copy link
Author

akarsh1995 commented Apr 23, 2022

@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
Copy link
Author

@tobz, Any update on this?

@tobz
Copy link
Member

tobz commented May 2, 2022

@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
Copy link
Contributor

We have decided to go with #688 instead.

@Darksonn Darksonn closed this Jan 26, 2023
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 dark mode
3 participants