Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Update Callout documentation on links #50131

Merged
merged 6 commits into from
Apr 28, 2023
Merged

Docs: Update Callout documentation on links #50131

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cc98dba
Fixes #50125
bph Apr 27, 2023
4d7edc8
HTML encoding needed
bph Apr 27, 2023
40ebd28
add call out to the link section, too.
bph Apr 27, 2023
d285bc2
move the callout
bph Apr 27, 2023
58db1d8
use absolute URLs instead
bph Apr 27, 2023
1ad601f
absolute URL here as well.
bph Apr 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/contributors/documentation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,10 @@ Use the full directory and filename from the Gutenberg repository, not the publi

An example, the link to this page is: `/docs/contributors/documentation/README.md`

<div class="callout callout-warning">
<b>Note:</b> The usual link transformation is not applied to links in callouts. See below.
</div>

### Code examples

The code example in markdown should be wrapped in three tick marks \`\`\` and should additionally include a language specifier. See this [GitHub documentation around fenced code blocks](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks).
Expand Down Expand Up @@ -132,7 +136,7 @@ The preferred format for code examples is JSX, this should be the default view.

The Block Editor handbook supports the same [notice styles as other WordPress handbooks](https://make.wordpress.org/docs/handbook/documentation-team-handbook/handbooks-style-and-formatting-guide/#formatting). However, the shortcode implementation is not ideal with the different locations the block editor handbook documentation is published (npm, GitHub).

The recommended way to implement in markdown is to use the raw HTML and `callout callout-LEVEL` classes. For example:
The recommended way to implement in markdown is to use the raw HTML and`callout callout-LEVEL` classes. For example:

```html
<div class="callout callout-info">This is an **info** callout.</div>
Expand All @@ -156,6 +160,13 @@ This is an **alert** callout.
This is a **warning** callout.
</div>

<div class="callout callout-warning">
Note: In callout notices, links also need to be HTML `&lt;a href>&lt;/a>` notations.
The usual link transformation is not applied to links in callouts.
For instance, to reach the Getting started > Create Block page the URL in GitHub is
https://developer.wordpress.org/docs/getting-started/create-block/README.md
and will have to be hardcoded for the endpoint in the Block Editor Handbook as <a href="../getting-started/create-block/">../getting-started/create-block/</a> to link correctly in the handbook.
bph marked this conversation as resolved.
Show resolved Hide resolved
</div>
### Editor config

You should configure your editor to use Prettier to auto-format markdown documents. See the [Getting Started documentation](/docs/contributors/code/getting-started-with-code-contribution.md) for complete details.
Expand Down
5 changes: 3 additions & 2 deletions docs/reference-guides/block-api/block-registration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
Block registration API reference.

<div class="callout callout-alert">
You can use the functions documented on this page to register a block with JavaScript only on the client, but the recommended method is to register new block types also with PHP on the server using the `block.json` metadata file. See <a href="/docs/reference-guides/block-api/block-metadata.md">metadata documentation for complete information</a>
<a href="/docs/getting-started/create-block/README.md">Learn how to create your first block</a> for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all you need to know to get started with creating blocks.
You can use the functions documented on this page to register a block with JavaScript only on the client, but the recommended method is to register new block types also with PHP on the server using the `block.json` metadata file. See <a href="block-metadata/">metadata documentation for complete information</a>
<br/>
<a href="../getting-started/create-block/">Learn how to create your first block</a> for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all you need to know to get started with creating blocks.
</div>

## `registerBlockType`
Expand Down