Add initial navigation editor user docs #34985
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
talldan
added
[Type] Enhancement
talldan
requested review from
adamziel,
draganescu,
getdave,
kevin940726 and
tellthemachines
as code owners
|
Size Change: -199 B (0%) Total Size: 1.06 MB
ℹ️ View Unchanged
|
getdave
approved these changes
Sep 21, 2021
|
|
||
| # Block-based menu editor | ||
|
|
||
| The Block-based Navigation Editor brings the power of blocks to the Appearance > Navigation section in the WordPress Administration Screens allowing you use blocks to create menus. |
There was a problem hiding this comment.
Are we going to use the term menu or navigation? Menu doesn't sort of bind us to the classic menus screen...
There was a problem hiding this comment.
Yeah, I don't know! This question was also asked in the tracking issue. The button is currently 'New menu' in the editor, so I think as longs as the docs match the UI it's ok.
If/when the UI changes we can update the docs to match.
I personally can't see a switch entirely to 'Navigation' because 'New navigation' doesn't sound right. That might be because navigation is an uncountable noun, so it can't represent a tangible item.
There was a problem hiding this comment.
Oh, I see now you were referring to the title. Good point, I changed it.
|
|
||
| The interface replicates the Post Editor experience, allowing you to use similar workflows like drag and drop. | ||
|
|
||
| The editor provides access to all the menus created using the previous Menu screen in WordPress. |
There was a problem hiding this comment.
Suggested change
| The editor provides access to all the menus created using the previous Menu screen in WordPress. | |
| The editor provides access to all/any of the menus you created using the classic `Menus` screen in WordPress. |
There was a problem hiding this comment.
It's a nitpick, but I don't think 'you' is correct because different users could've created the menus, not just the reader. 😄
I'm a bit hesitant about saying 'classic' right now. Widget docs use the term 'previous', so I think it's good to stay consistent. This might change if we decide to use the term 'classic' in the UI or as a plugin.
The sentence is a bit awkward, but I don't know, I think I'll leave it for now.
|
|
||
| The editor provides access to all the menus created using the previous Menu screen in WordPress. | ||
|
|
||
| New menus can also easily be created, providing options to easily create a menu from an existing page hierarchy, by copying an existing menu, or creating a blank menu. |
There was a problem hiding this comment.
Suggested change
| New menus can also easily be created, providing options to easily create a menu from an existing page hierarchy, by copying an existing menu, or creating a blank menu. | |
| New menus can also easily be created: | |
| * from an existing `Page` hierarchy | |
| * by copying an existing menu, | |
| * by creating a blank menu. |
There was a problem hiding this comment.
I've gone half and half on this. I don't like leaving out that the editor 'provides options', because otherwise the 'by copying an existing menu' part makes it sound like the user has to find the menu, copy it, and then paste it.
Lets avoid using backticks for words because this formats it like code, which I don't think is relevant for user docs.
I only used them for the + button because it makes it look more like the icon, but I expect there will be images in the final docs.
|
|
||
| 1. Click one of the `+` buttons. | ||
| 2. Select the type of link you want to add. | ||
| 3. Use the dialog to search for the item you want to link to. For a custom link, type in a URL and hit 'Enter'. |
There was a problem hiding this comment.
Suggested change
| 3. Use the dialog to search for the item you want to link to. For a custom link, type in a URL and hit 'Enter'. | |
| 3. One the item is inserted into the editor, use the dialog to search for the item you want to link to. Alternatively, for a custom link, type in a URL and hit 'Enter'. |
There was a problem hiding this comment.
I don't think 'Once the item is inserted into the editor' is needed because the line above tells them to insert it and it happens immediately.
I have changed this by splitting out the instructions for a custom link, which I think makes it clearer.
| 2. Select the type of link you want to add. | ||
| 3. Use the dialog to search for the item you want to link to. For a custom link, type in a URL and hit 'Enter'. | ||
|
|
||
| ### How to add a submenu block |
There was a problem hiding this comment.
Suggested change
| ### How to add a submenu block | |
| ### How to add a submenu |
The goal is to add a submenu. At this point the "block" is an implementation detail.
There was a problem hiding this comment.
Yeah, I initially started with that, but added 'block' because this heading was very similar to 'How to create a menu' 🤔
Maybe that's ok, I'll change it back.
There was a problem hiding this comment.
I changed this and the above heading to 'How to insert a link' and 'How to insert a submenu', which I think is better all round 👍
|
|
||
| ### How to add a submenu block | ||
|
|
||
| There are two ways to create a submenu, the first option is to create a new submenu from scratch: |
There was a problem hiding this comment.
Suggested change
| There are two ways to create a submenu, the first option is to create a new submenu from scratch: | |
| There are two ways to create a submenu. | |
| The first option is to create a new submenu from scratch: |
|
Excellent work Dan! Thank you for spending time on this :) |
spacedmonkey
approved these changes
Sep 21, 2021
spacedmonkey
approved these changes
Sep 21, 2021
oandregal
reviewed
Oct 2, 2021
| role="menuitem" | ||
| icon={ external } | ||
| href={ __( | ||
| 'https://github.com/WordPress/gutenberg/tree/trunk/packages/edit-navigation/docs/user-documentation.md' |
There was a problem hiding this comment.
👋 I was translating some strings to my native language and ran into this one. I've seen it in use in a couple other places as well, so I'm curious as to why we use _() within the href attribute.
There was a problem hiding this comment.
Thanks for pointing that out. It's not needed here, as these docs aren't internationalized.
I'll spin up a PR to remove it (#35313).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Fixes #34266
Adds some initial navigation editor user documentation.
This is heavily based on the docs for the widget editor (https://wordpress.org/support/article/block-based-widgets-editor/).
As the editor is developed these can be refined before eventually making their way to the wordpress.org website prior to release.
I've also added a link to the documentation from the editor in this PR, but unfortunately that won't work until the PR is merged.