# Shortcode

Shortcode module for WordPress.

## Installation

Install the module

```bash
npm install @wordpress/shortcode --save
```

_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._

## API

<!-- START TOKEN(Autogenerated API docs) -->

### attrs

Parse shortcode attributes.

Shortcodes accept many types of attributes. These can chiefly be divided into named and numeric attributes:

Named attributes are assigned on a key/value basis, while numeric attributes are treated as an array.

Named attributes can be formatted as either `name="value"`, `name='value'`, or `name=value`. Numeric attributes can be formatted as `"value"` or just `value`.

_Parameters_

-   _text_ `string`: Serialised shortcode attributes.

_Returns_

-   `ShortcodeAttrs`: Parsed shortcode attributes.

### default

Creates a shortcode instance.

To access a raw representation of a shortcode, pass an `options` object, containing a `tag` string, a string or object of `attrs`, a string indicating the `type` of the shortcode ('single', 'self-closing', or 'closed'), and a `content` string.

_Type_

-   `Shortcode`

### fromMatch

Generate a Shortcode Object from a RegExp match.

Accepts a `match` object from calling `regexp.exec()` on a `RegExp` generated by `regexp()`. `match` can also be set to the `arguments` from a callback passed to `regexp.replace()`.

_Parameters_

-   _match_ `Match`: Match array.

_Returns_

-   `ShortcodeInstance`: Shortcode instance.

### next

Find the next matching shortcode.

_Parameters_

-   _tag_ `string`: Shortcode tag.
-   _text_ `string`: Text to search.
-   _index_ `number`: Index to start search from.

_Returns_

-   `ShortcodeMatch | undefined`: Matched information.

### regexp

Generate a RegExp to identify a shortcode.

The base regex is functionally equivalent to the one found in `get_shortcode_regex()` in `wp-includes/shortcodes.php`.

Capture groups:

1.  An extra `[` to allow for escaping shortcodes with double `[[]]`
2.  The shortcode name
3.  The shortcode argument list
4.  The self closing `/`
5.  The content of a shortcode when it wraps some content.
6.  The closing tag.
7.  An extra `]` to allow for escaping shortcodes with double `[[]]`

_Parameters_

-   _tag_ `string`: Shortcode tag.

_Returns_

-   `RegExp`: Shortcode RegExp.

### replace

Replace matching shortcodes in a block of text.

_Parameters_

-   _tag_ `string`: Shortcode tag.
-   _text_ `string`: Text to search.
-   _callback_ `ReplaceCallback`: Function to process the match and return replacement string.

_Returns_

-   Text with shortcodes replaced.

### string

Generate a string from shortcode parameters.

Creates a shortcode instance and returns a string.

Accepts the same `options` as the `shortcode()` constructor, containing a `tag` string, a string or object of `attrs`, a boolean indicating whether to format the shortcode using a `single` tag, and a `content` string.

_Parameters_

-   _options_ `ShortcodeOptions`: Shortcode options.

_Returns_

-   `string`: String representation of the shortcode.

<!-- END TOKEN(Autogenerated API docs) -->

## Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
