Skip to content

Docs: Update link for Inner Blocks - #14941

Merged
mkaz merged 2 commits into
masterfrom
docs/fix/inner-block-links
Apr 12, 2019
Merged

mkaz merged 2 commits into
masterfrom
docs/fix/inner-block-links

Conversation

@mkaz

@mkaz mkaz commented Apr 12, 2019

Copy link
Copy Markdown
Member

Description

The Inner Blocks component is linked to the wrong spot, the old link is going to /packages/editor/src/components/inner-block/README.md the new location should be block-editor package.

This PR updates the link on block-registration, and block-templtes page.

However, I don't think the actually Inner Block documentation is being published anywhere.

@nosolosw if I look in the source repo on Github, the readme file is there for Inner Blocks.
See: https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inner-blocks

However, if I look at the Gutenberg Handbook, it looks empty here
https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-block-editor/#InnerBlocks

Types of changes

Documentation

@jorgefilipecosta jorgefilipecosta left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

* **Type:** `Array`

Blocks are able to be inserted into blocks that use [`InnerBlocks`](/packages/editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available as a nested block. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block.
Blocks are able to be inserted into blocks that use [`InnerBlocks`](/packages/block-editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available as a nested block. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mmm, it looks like we have a bunch of links pointing to the wrong URLs. We should either:

  1. Use full URLs for files that aren't published to the handbook (all component's READMEs, things that live within */src/*, etc.): https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-block-editor/#InnerBlocks

  2. Use relative URLs to the handbook docs: /docs/designers-developers/developers/packages/packages-block-editor/#InnerBlocks

@oandregal

Copy link
Copy Markdown
Member

However, I don't think the actually Inner Block documentation is being published anywhere.

Yup, it's not. To my knowledge, it was never published to the handbook. Note that https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-block-editor/#InnerBlocks uses the info from the JSDoc comments (in this case there is none).

Here are some thoughts on how we could improve this:

  • most components aren't documented (as in: they have JSDoc comments).
  • many components do have a README file.

What if we moved the relevant info from the component's README to JSDoc comments, then automatically fill both the component's README and the handbook page? This is one of the tasks I'm tracking on #14227 At the moment the ./bin/update-readmes only updates the packages' README, but we could adapt it to also update the inner component's READMEs.

@mkaz

mkaz commented Apr 12, 2019

Copy link
Copy Markdown
Member Author

Ok, I'll merge this one which "fixes" the link at least to the right packages section.

We can track the sub-components on your at #14227 - I need to dig in a little more to understand completely. My initial hunch is that it is probably best to try and match the handbook docs to Github directory structure as much as possible.

The /packages/ relative URL does get transform to work when viewing the handbook, but not sure if the links work properly in the npm and github contexts of viewing documentation. A quick search and it looks like 20 or so spots are linking this way.

@mkaz
mkaz merged commit 992b330 into master Apr 12, 2019
@mkaz
mkaz deleted the docs/fix/inner-block-links branch April 12, 2019 13:23
mchowning pushed a commit to mchowning/gutenberg that referenced this pull request Apr 15, 2019
* Update link for Inner Blocks, component of block-editor package

* Add back whitespace in title, fixed in different PR
@youknowriad youknowriad added this to the 5.5 (Gutenberg) milestone Apr 15, 2019
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.

4 participants