docs(v2): add manual migration guide for versioning #2047
Conversation
endiliey
added
the
pr: documentation
|
Deploy preview for docusaurus-2 ready! Built with commit 9939058 |
|
Deploy preview for docusaurus-preview ready! Built with commit 9939058 |
|
|
||
| ## Versioned Site | ||
|
|
||
| > :warning: _This section is a work in progress._ |
There was a problem hiding this comment.
We need to think about the version page. I mean that it immediately exists if versioning is used, instead of having users manually create it. WDYT?
There was a problem hiding this comment.
Hmmm, but 'versions' page route is handled by @docusaurus/plugin-content-pages and not @docusaurus/plugin-content-docs.
I'm afraid that if versions page route is handled by docs plugin, this means they cannot customize it.
In docusaurus v1 it was possible because all functionality is too coupled, but in v2 we might allow just docs plugin with even different theme package. (Edit: or even without pages plugin)
But I think we can just mention in the docs they can copy our versions page 😆
There was a problem hiding this comment.
Oh yes, I would then create a command that would copy the template for the version page :)
By the way, I would change the display of the current version in navbar to something like this
That is better?
There was a problem hiding this comment.
Oh yes, I would then create a command that would copy the template for the version page :)
At some point we'll need an automated script that will do lot of stuff for us when we migrate v1 to v2 versioned site. But I think its better to roll it out to v2 users first, dogfood it and make sure its fine before creating such scripts.
So will clicking the logo will link to /versions page or not? Or its just styling the Navbar Links ?
Wanted to make sure it looks good on mobile too
There was a problem hiding this comment.
This is just a prototype, in the current implementation, this will also be a separate menu item (yes, styling), but then on mobiles, version will not be visibled. Therefore, we need to do this as part of the logo itself, but for this we need to swizzle NavBar, otherwise how to add custom HTML to the logo item?
There was a problem hiding this comment.
Maybe we can just make it not complex
We create new API
// docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
title: 'Site Title',
logo: {
alt: 'Site Logo',
src: 'img/logo.svg',
+ defaultVersionShown: '2.0.0-alpha.36'
},
}
}When on /docs/next/, or any other docs route, the layout is aware which version it is in
So we can pass it to navbar and display the current docs version we're reading in
It's like this but we can move it to top (near logo) (ignore the bad css here, i used chrome to hack this out)
If they are in '/pages/about', '/blog/xxx', we just show the defaultVersion,
Clicking the logo will link to /versions if defaultVersionShown is defined
WDYT
There was a problem hiding this comment.
But need to make sure this looks good on mobile too :(
There was a problem hiding this comment.
So we want to display the version for all users (like React website)? I would do then not bind the version to the header. Something like this:
themeConfig: {
...
version: {
current:
showInNavbar:
}
...
}
Or simpler - we can take the first version element as on the versions page
There was a problem hiding this comment.
hmmm. its kinda a hard call because only docs is versioned
I think at the end of the day, we want something like in infima, using the dropdown https://infima-dev.netlify.com/
lets not do anything for now. Its too coupled with infima. I believe @yangshun has his plan for how the site should look like.
Motivation
Add add manual migration guide for versioning for now.
Have you read the Contributing Guidelines on pull requests?
yes
Test Plan
N/A just documentation changes