-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Tutorial: Create Extensions
- Disable Element
- Change Element Markup
- Add Inline Element
- Add Multi-Line Element
- Line & Block Element Structure
This example disables Header elements. That is, both Atx Header and Setext Header elements.
class Extension extends Parsedown
{
protected function blockHeader($Line)
{
return;
}
protected function blockSetextHeader($Line, array $Block = null)
{
return;
}
}
You can use the same approach for other elements types. This includes inline element types. For example, to disable Image elements you should override inlineImage
.
Note that to disable all headers you should also disable support for HTML. You can do that by setting the MarkupEscaped
option to true
.
This example prepends a base path to the src
of Image elements.
class Extension extends Parsedown
{
private $baseImagePath = 'http://cdn.example.com/';
protected function inlineImage($excerpt)
{
$image = parent::inlineImage($excerpt);
if ( ! isset($image))
{
return null;
}
$image['element']['attributes']['src'] = $this->baseImagePath . $image['element']['attributes']['src'];
return $image;
}
}
You can use the same approach for other element types.
This example adds a ColoredText element. You can find a description of this element at https://github.com/erusev/parsedown/issues/262.
class Extension extends Parsedown
{
function __construct()
{
$this->InlineTypes['{'][]= 'ColoredText';
$this->inlineMarkerList .= '{';
}
protected function inlineColoredText($excerpt)
{
if (preg_match('/^{c:([#\w]\w+)}(.*?){\/c}/', $excerpt['text'], $matches))
{
return array(
// How many characters to advance the Parsedown's
// cursor after being done processing this tag.
'extent' => strlen($matches[0]),
'element' => array(
'name' => 'span',
'text' => $matches[2],
'attributes' => array(
'style' => 'color: ' . $matches[1],
),
),
);
}
}
}
You can use the same approach for other element types.
This example extends the bold element (**) to work on multiple lines.
class Extension extends Parsedown
{
/**
* The array index is the first character of the pattern to match.
* It is not possible to define patterns longer than one character directly here, as only the first
* character of the line will be checked. (eg. Setting $this->BlockTypes['{tag'] won't work.)
*
* The second array is a list of all functions that should be called when the character is found.
*
* Leave out the 'block' or 'inline' part of the function name, as it will be prepended automatically.
*/
function __construct()
{
$this->BlockTypes['*'][] = 'BoldText';
}
protected function blockBoldText($line, $block)
{
if (preg_match('/^\*\*/', $line['text'], $matches))
{
return array(
'char' => $line['text'][0],
'element' => array(
'name' => 'strong',
'text' => '',
),
);
}
}
/**
* Appending the word `continue` to the function name will cause this function to be
* called to process any following lines, until $block['complete'] is set to be 'true'.
*/
protected function blockBoldTextContinue($line, $block)
{
if (isset($block['complete']))
{
return;
}
// A blank newline has occurred.
if (isset($block['interrupted']))
{
$block['element']['text'] .= "\n";
unset($block['interrupted']);
}
// Check for end of the block.
if (preg_match('/\*\*/', $line['text']))
{
$block['element']['text'] = substr($block['element']['text'], 1);
// This will flag the block as 'complete':
// 1. The 'continue' function will not be called again.
// 2. The 'complete' function will be called instead.
$block['complete'] = true;
return $block;
}
$block['element']['text'] .= "\n" . $line['body'];
return $block;
}
/**
* Appending the word `complete` to the function name will cause this function to be
* called when the block is marked as *complete* (see the previous method).
*/
protected function blockBoldTextComplete($block)
{
return $block;
}
}
The $line
structure represents a single line of text from the input Markdown content.
-
text
: This is the actual content of the line being parsed. -
indent
: Represents the number of spaces at the start of the line. Useful for identifying block elements, like blockquotes or code blocks. -
body
: It's the content of the line with the leading whitespace (determined byindent
) removed.
The $block
structure represents a block-level element in Markdown, such as paragraphs, lists, headers, blockquotes, and more.
-
type
: Identifies the type of the block (e.g., 'Paragraph', 'Header', 'List', etc.). -
indent
: The base indentation level of the block. -
handler
: Specifies how the content of the block should be processed. It usually contains:-
function
: The method used to process the block's content. -
argument
: Arguments passed to the processing function. Typically, it's the content of the block. -
destination
: Determines where the output of the processing function should be stored.
-
-
element
: Contains the final parsed content of the block, ready to be converted to HTML. It typically includes:-
name
: The name of the HTML element that represents this block. -
text
: The text content of the element. -
elements
: An array of sub-elements contained within this block. -
attributes
: Any attributes to be added to the HTML element.
-
-
pattern
: (For lists) A regex pattern to match the list marker. -
data
: Additional data specific to the block type. For example, for lists, it can contain the marker type (*
,-
, or+
for unordered lists and numbers for ordered lists).