Docs: Update folder structure and make all internal handbook links relative #6161
Conversation
docs/language.md
Outdated
| @@ -79,7 +79,7 @@ After running this through the parser we're left with a simple object we can man | |||
|
|
|||
| This has dramatic implications for how simple and performant we can make our parser. These explicit boundaries also protect damage in a single block from bleeding into other blocks or tarnishing the entire document. It also allows the system to identify unrecognized blocks before rendering them. | |||
|
|
|||
| _N.B.:_ The defining aspect of blocks are their semantics and the isolation mechanism they provide; in other words, their identity. On the other hand, where their data is stored is a more liberal aspect. Blocks support more than just static local data (via JSON literals inside the HTML comment or within the block's HTML), and more mechanisms (_e.g._, global blocks or otherwise resorting to storage in complementary `WP_Post` objects) are expected. See [attributes](../block-api/attributes) for details. | |||
| _N.B.:_ The defining aspect of blocks are their semantics and the isolation mechanism they provide; in other words, their identity. On the other hand, where their data is stored is a more liberal aspect. Blocks support more than just static local data (via JSON literals inside the HTML comment or within the block's HTML), and more mechanisms (_e.g._, global blocks or otherwise resorting to storage in complementary `WP_Post` objects) are expected. See [attributes](./block-api/attributes.md) for details. | |||
There was a problem hiding this comment.
This is an example where it will no longer work as expected. Unless we put this file inside docs/language/README.md and update the regular expression to remove README.md from links, too.
I'm all for making the experience of writing docs less handbook-dependent, especially if that means that you can structure docs in a way that makes sense regardless of context—and keeping The way I see it, we can add further improvements to the handbook theme beyond https://meta.trac.wordpress.org/changeset/7104. Whenever fitting, introducing certain tokens or conventions in the docs could help the theme perform better corrections. For instance, regarding pointing from
Perhaps in these cases we could disambiguate, e.g. write the URL as |
Great idea, it should work properly. I will update this PR to match this proposal. We will still have to fix the part on .org side to make sure it understand this convention :) |
|
Thanks for working on this, I like how it makes writing the docs easier as well as solving the issue of the github links not working properly. |
Props to @mcsf for sharing this neat idea :)
|
This is updated, all links to GitHub documents located in
I think those are all 4 possibilities. |
|
.org handler was added here: https://meta.trac.wordpress.org/changeset/7141 |
The docs file structure was updated in WordPress#6161. This broke the FAQ link in our README. This PR updates the link with the correct destination.
The docs file structure was updated in #6161. This broke the FAQ link in our README. This PR updates the link with the correct destination.
Description
This is follow-up for #6126. With the https://meta.trac.wordpress.org/changeset/7104 change introduced by @pento we can now update all docs links to use GitHub relative urls to make navigation work with both handbook and GitHub.
This PR tries to come up with a folder structure that will work for all existing urls. I think it works fine for all urls that are referencing other documents for those documents that are in subfolders.
I need to think a bit more about it. With the changes proposed it works fine on GitHub but might not work in all cases in Gutenberg handbook...