[Documentation] fix link to edit-post documentation

[torounit]

Description

Fixes #12332.

Fix link to edit-post documentation.

[gziolo]

@chrisvanpatten - we need to find a way to properly link urls to make them work with:

• handbook
• GitHub
• npm

The correct full url is:
https://github.com/WordPress/gutenberg/blob/master/packages/edit-post/README.md
or
https://www.npmjs.com/package/@wordpress/plugins

From npm it links to https://github.com/WordPress/gutenberg/blob/edit-post/ - which is also broken.

A simple approach would be to always link npm packages for packages README files. Any thoughts?

[chrisvanpatten]

@gziolo I’m open to ideas. Right now the parser on dot org requires a full relative path which also works on github, eg ../../../docs/path/to/file.md (or whatever tha path is) where you have to traverse up to the base of the repo, and then back down to your file.

Obviously that sucks from a UX perspective but also it does mean it works on GitHub and the handbook, although I hadn’t even considered there would be npm issues. Yay :)

For NPM readmes I think either the full URL is reasonable (I’d prefer linking to the GH version but the NPM version is fine too) but we need help from @dd32 (or someone else with bandwidth) to make sure the parser knows how to handle that and rewrite it to a handbook URL.

EDIT Actually looking at it again for npm we just may be able to do the full relative path as well and they’ll rewrite it too, I think. Worth trying that too for now?

[gziolo]

It looks like npm takes https://github.com/WordPress/gutenberg/tree/master/ as the current folder for docs. It seems like it reads it from package.json file. Maybe we should change some field there and it will magically work :)

[gziolo]

So I found related issues:
https://npm.community/t/relative-links-in-npm-readme-markdown-not-functional/1525/6

I can confirm that https://github.com/WordPress/gutenberg/tree/master/ is going to be considered as the root folder. To make it work for both NPM and GitHub we can use the following:
/packages/edit-post/README.md

I'm wondering if that would also work for docs:
/docs/designers-developers/key-concepts.md

@dd32 - assuming that I'm correct, would it be possible to make it work this way for the handbook? It seems like it would make it much easier at least on the GitHub side of things.

[gziolo]

Suggested change

	See [the edit-post module documentation](../packages-edit-post/) for available components.
	See [the edit-post module documentation](/packages/edit-post/) for available components.

It seems like it works properly when I try it in the preview mode.

[chrisvanpatten]

@gziolo I like the idea of /docs/xyz in theory, but does that work inside GitHub? Will GitHub just treat that as https://github.com/docs/xyz or correctly rewrite it? (I'll do a quick test unless someone chimes in)

EDIT: I'm an idiot, missed your review comment. That makes sense to me, I like the idea, as long as we can get the parser updated on dot org first so our links don't break for a third (or fourth or fifth? I'm losing track) time 😅

[gziolo]

You need to try with the file edit feature on GitHub and preview mode.

[dd32]

@dd32 - assuming that I'm correct, would it be possible to make it work this way for the handbook? It seems like it would make it much easier at least on the GitHub side of things.

@gziolo If i'm understanding correctly, you'd like to make links starting as /docs/... and /packages/... work the same way as the ../docs/ urls currently do? or should /packages/.. go to a subpage? etc.

If i'm misunderstanding, an exact list of how each should be treated would be helpful, similar to this:

• ../docs/(.+)$ => https://wordpress.org/gutenberg/handbook/$1
• /docs/(.+)$ => https://wordpress.org/gutenberg/handbook/$1

[gziolo]

All documentation pages for packages are grouped under: https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/

It looks like it will be a slightly different then. I will check also which different patterns we use. There should be also something custom for components from the components package. I will comment soon with the list of mappings.

[gziolo]

{
	"title": "Packages",
	"slug": "packages",
	"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/packages.md",
	"parent": "developers"
},
{
	"title": "@wordpress/edit-post",
	"slug": "packages-edit-post",
	"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/edit-post/README.md",
	"parent": "packages"
},
{
	"title": "Components",
	"slug": "components",
	"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/README.md",
	"parent": "developers"
},
{
	"title": "WithFilters",
	"slug": "with-filters",
	"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/components/src/higher-order/with-filters/README.md",
	"parent": "components"
},

I think we need to support 4 url patterns from the list extracted above. Turning them into absolute urls would end up with the following regular expressions for the handbook:

• /docs/(.+)$ => https://wordpress.org/gutenberg/handbook/$1
• /packages/components/README.md$ => https://wordpress.org/gutenberg/handbook/designers-developers/developers/components/
• /packages/components/(.+)/README.md$ => https://wordpress.org/gutenberg/handbook/designers-developers/developers/components/$1
• /packages/(.+)/README.md$ =. https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-$1/

It might be buggy but shares the general idea :)

[chrisvanpatten]

@gziolo @dd32 I think /docs/(.*) → https://wordpress.org/gutenberg/handbook/$1 is 100% safe to implement.

For package and component documentation, let's target that separately… I'll try to devote an hour or so today/tomorrow to figuring out there's a cleaner approach with packages and components. (I have an idea of two I want to try.)

[dd32]

I've added support for these links in https://meta.trac.wordpress.org/changeset/7989

As adding the extra links formats as mentioned by @gziolo in #12835 (comment) was easier to do at the same time, I've added them all - If they don't get used let me know and I'll pull them back out of the docs importer, but having them there doesn't negatively affect anything.

The old-style ../docs links still get processed as well, so a hard-cutover isn't needed or anything like that.

[gziolo]

@dd32 I did some debugging with the following snippet:

$markdown = preg_replace( '/(\[.*?\]\((\.\.\/)+.*?)((\/readme)?\.md)?(#.*)?\)/i', '$1$5)', $markdown );
$markdown = preg_replace( '@(\[.*?\])\(/packages/(.*?)/?(#.*)?\)@i', '$1(https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-$2/$3)', $markdown );
print $markdown;

It works perfectly fine for:

• /packages/edit-post -> https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-edit-post

However, it doesn't remove README.md as it happens for the existing paths relative to docs/

• /packages/edit-post/REAMDE.md -> https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-components/README.md/

[gziolo]

It looks good now. Thanks for opening this PR 👍

[gziolo]

I can confirm that the link in https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-plugins/ works as expected 🎉

[chrisvanpatten]

Thanks @gziolo!! 🎉

[dd32]

@dd32 I did some debugging with the following snippet:
However, it doesn't remove README.md as it happens for the existing paths relative to docs/

• /packages/edit-post/REAMDE.md -> https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-components/README.md/

Ahh yes, I had forgotten that change was actually needed.. Fixed up in https://meta.trac.wordpress.org/changeset/7993
(That typo of 'REAMDE' in your example threw me debugging the regex for far too long..)