Laravel Markdown

https://github.com/jeffersongoncalves/laravel-markdown
Admin
Laravel Markdown is a CommonMark renderer for Laravel featuring GitHub Flavored Markdown, optional...
Tokens:18,089
Snippets:155
Trust Score:9.8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Basic facade usage example

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

Renders a simple Markdown string to HTML. The output is shown in the comment.

```php
use JeffersonGoncalves\Markdown\Facades\Markdown;

$html = Markdown::render('# Hello **world**');
// <h1>Hello <strong>world</strong></h1>
```

--------------------------------

### Install laravel-markdown via Composer

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/resources/boost/skills/markdown-development/SKILL.md

Install the package with Composer. Requires PHP 8.4+, Laravel 11/12/13, spatie/laravel-package-tools ^1.14, league/commonmark ^2.4, and tempest/highlight ^2.25.

```bash
composer require jeffersongoncalves/laravel-markdown
```

--------------------------------

### Basic usage example

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-renderer.md

Instantiates MarkdownRenderer and renders a simple Markdown string with a heading and bold text.

```php
use JeffersonGoncalves\Markdown\MarkdownRenderer;

$renderer = new MarkdownRenderer;
$html = $renderer->render('# Hello **world**');
// $html contains <h1>Hello <strong>world</strong></h1>
```

--------------------------------

### Run tests, coverage, static analysis, and formatting

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/resources/boost/skills/markdown-development/SKILL.md

Commands to run the test suite with Pest, generate coverage, run PHPStan static analysis, and format code with Pint.

```bash
# Run all tests
vendor/bin/pest

# Run with coverage
vendor/bin/pest --coverage

# Static analysis
vendor/bin/phpstan analyse

# Code formatting
vendor/bin/pint
```

--------------------------------

### Example with heading permalinks and per-call options

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-renderer.md

Shows using headingPermalinks and options parameters. The first call adds anchor links; the second preserves raw HTML only for that call.

```php
$renderer = app(MarkdownRenderer::class);

$html = $renderer->render($readme, headingPermalinks: true);
// headings get an <a class="md-anchor"> and GitHub-style id="{slug}" (see configuration.md)

$html = $renderer->render($trustedBody, options: ['html_input' => 'allow']);
// this call only preserves raw HTML; the stored config is untouched
```

--------------------------------

### Flushing after runtime config change

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Example showing how to flush caches after changing markdown.* config at runtime, so the next render() picks up the new configuration. Useful in tests.

```php
use JeffersonGoncalves\Markdown\Markdown;

Markdown::render('# warm up');           // builds and caches the converter

config()->set('markdown.html_input', 'allow');
Markdown::flush();                        // drop caches

$html = Markdown::render('<div>hi</div>'); // now preserves the <div>
```

--------------------------------

### Error-handling / safety consideration example

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-renderer.md

Shows try-catch around rendering untrusted input with default config, noting that exceptions propagate from underlying libraries.

```php
use JeffersonGoncalves\Markdown\MarkdownRenderer;

try {
    $html = (new MarkdownRenderer)->render($userInput, headingPermalinks: true);
    // default config => raw HTML escaped, safe to echo
} catch (\Throwable $e) {
    // no package-specific exception; any failure bubbles up from the
    // underlying CommonMark/tempest-highlight stack
    report($e);
}
```

--------------------------------

### Package structure tree

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/resources/boost/skills/markdown-development/SKILL.md

Shows the package's source and config file layout, including the service provider, static render engine, renderer wrapper, facade, and config file.

```text
src/
  MarkdownServiceProvider.php   # Registers the package + config file + @markdown Blade directive
  Markdown.php                  # Static render() engine (memoized converters)
  MarkdownRenderer.php          # Container-resolvable wrapper behind the facade
  Facades/Markdown.php          # `Markdown` facade
config/
  markdown.php                  # html_input, allow_unsafe_links, heading_permalink
```

--------------------------------

### Publish markdown config

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/resources/boost/skills/markdown-development/SKILL.md

Publish the package configuration file using the markdown-config tag. The config file contains html_input, allow_unsafe_links, and heading_permalink settings.

```bash
php artisan vendor:publish --tag="markdown-config"
```

--------------------------------

### Flush memoized converters after runtime config change

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/configuration.md

Call Markdown::flush() after changing markdown.* config at runtime to drop memoized converters and the highlighter, so the next render uses the new config. The example toggles html_input to 'allow' and then renders a <div> tag, which is preserved.

```php
config()->set('markdown.html_input', 'allow');
Markdown::flush();
$html = Markdown::render('<div>hi</div>'); // now preserved
```

--------------------------------

### Basic @markdown usage

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Echoes rendered HTML. The first example shows inline Markdown; the second uses a variable. Comments show the expected output.

```blade
@markdown('# Hello **world**')
{{-- echoes <h1>Hello <strong>world</strong></h1> ---}}

@markdown($articleBody)
{{-- echoes the rendered HTML of $articleBody ---}}
```

--------------------------------

### Get rendered HTML string directly

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Use the static PHP class when you need the string instead of echoing. The directive itself only echoes output.

```php
$html = \JeffersonGoncalves\Markdown\Markdown::render($source);
```

--------------------------------

### Pest tests for Markdown rendering features

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/resources/boost/skills/markdown-development/SKILL.md

Pest tests verifying GFM table rendering, fenced code highlighting, and heading permalinks. Uses the Markdown::render method with optional headingPermalinks parameter.

```php
use JeffersonGoncalves\Markdown\Markdown;

it('renders a GFM table', function () {
    $html = Markdown::render("| A | B |\n| - | - |\n| 1 | 2 |");

    expect($html)->toContain('<table>')->toContain('<td>1</td>');
});

it('highlights fenced code blocks', function () {
    $html = Markdown::render("```php\necho 'hi';\n```");

    expect($html)->toMatch('/class="hl-[a-z]+"/');
});

it('adds md-anchor anchors only when enabled', function () {
    expect(Markdown::render('# H', headingPermalinks: true))->toContain('md-anchor');
    expect(Markdown::render('# H'))->not->toContain('md-anchor');
});
```

--------------------------------

### Markdown::render() public API

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/resources/boost/skills/markdown-development/SKILL.md

Static render method signature. Accepts markdown string, optional heading permalinks flag, and per-call options overriding config keys. Returns HTML string. Converters are memoized per (permalinks flag, options) combination.

```php
JeffersonGoncalves\Markdown\Markdown::render(
    string $markdown,
    bool $headingPermalinks = false,
    array $options = [],        // per-call overrides of the config keys
): string
```

--------------------------------

### Default markdown.php configuration for html_input, allow_unsafe_links, and heading_permalink

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/resources/boost/skills/markdown-development/SKILL.md

Configuration array read inside render() with hardcoded defaults as fallbacks. Each key can be overridden per call via $options. The heading_permalink config is only applied when render(..., headingPermalinks: true) is called. html_input defaults to 'escape' for safe-by-default rendering of untrusted input.

```php
'html_input' => 'escape',           // 'allow' | 'escape' | 'strip'
'allow_unsafe_links' => false,
'heading_permalink' => [
    'symbol' => '#',
    'html_class' => 'md-anchor',
    'id_prefix' => '',   // '' = bare GitHub-style ids (id="{slug}")
],
```

--------------------------------

### Run Tests with Composer

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/README.md

Execute the test suite using Composer. Run this command from the project root to run all tests.

```bash
composer test
```

--------------------------------

### Mocking the facade in application code

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

Shows how to mock the facade's render method in tests using shouldReceive, with expected arguments and return value.

```php
use JeffersonGoncalves\Markdown\Facades\Markdown;

// Swap the underlying renderer ahead of a controller test:
Markdown::shouldReceive('render')
    ->once()
    ->with('# Hello', false, [])
    ->andReturn('<h1>Hello</h1>');
```

--------------------------------

### Facade usage with heading permalinks and per-call options

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

Shows how to enable heading permalinks and pass per-call configuration options like 'html_input'.

```php
use JeffersonGoncalves\Markdown\Facades\Markdown;

$html = Markdown::render($readme, headingPermalinks: true);
$html = Markdown::render($trustedMarkdown, options: ['html_input' => 'allow']);
```

--------------------------------

### Basic Markdown Rendering

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/README.md

Render GitHub Flavored Markdown to HTML using the Markdown facade. Optionally enable heading permalink anchors by passing headingPermalinks: true.

```php
use JeffersonGoncalves\Markdown\Markdown;

// Render GitHub Flavored Markdown to HTML
$html = Markdown::render('# Hello **world**');

// Enable heading permalink anchors (adds <a class="md-anchor"> to each heading)
$html = Markdown::render($readme, headingPermalinks: true);
```

--------------------------------

### Import the Markdown facade

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

Import the facade class for static access to the rendering API.

```php
use JeffersonGoncalves\Markdown\Facades\Markdown;
```

--------------------------------

### configurePackage method signature

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Declares the configurePackage method that configures the package via the provided Package instance.

```php
public function configurePackage(Package $package): void
```

--------------------------------

### Configure HTML Input to Allow Raw HTML

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/README.md

Set 'html_input' to 'allow' in config/markdown.php to preserve raw HTML in markdown source. Only use for trusted content; output becomes unsafe for untrusted input and must be sanitized.

```php
// config/markdown.php
'html_input' => 'allow',
```

--------------------------------

### Three usage patterns for MarkdownRenderer

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-renderer.md

Shows direct instantiation, container resolution, and facade usage to reach the same rendering logic.

```php
// 1. Direct instantiation
$renderer = new MarkdownRenderer;
$html = $renderer->render('# Hello');

// 2. Through the container
$renderer = app(MarkdownRenderer::class);
$html = $renderer->render('# Hello');

// 3. Through the facade (see markdown-facade.md)
use JeffersonGoncalves\Markdown\Facades\Markdown;
$html = Markdown::render('# Hello');
```

--------------------------------

### Facade Markdown::render() with $options

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/configuration.md

Renders Markdown to HTML via the facade, with the same per-call options as the static Markdown::render().

```APIDOC
## [POST] Facade Markdown::render()

### Description
Renders Markdown content to HTML using the facade. Accepts an optional $options array to override configuration for this call only.

### Method
POST (conceptual)

### Endpoint
Markdown::render($markdown, $options = [])

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **markdown** (string) - Required - The Markdown content to render.
- **options** (array) - Optional - Per-call options. Keys:
  - `html_input` (string) - Optional - 'escape', 'allow', or 'strip'. Overrides config('markdown.html_input').
  - `allow_unsafe_links` (bool) - Optional - Overrides config('markdown.allow_unsafe_links').
  - `heading_permalink` (array) - Optional - Keys: `symbol`, `html_class`, `id_prefix`. Only used when headingPermalinks is true.

### Request Example
```php
use JeffersonGoncalves\Markdown\Facades\Markdown;

$html = Markdown::render($markdown, options: ['html_input' => 'allow']);
```

### Response
#### Success Response (200)
- **html** (string) - The rendered HTML.

#### Response Example
```html
<div>hi</div>
```

```

--------------------------------

### Published Config File Contents

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/README.md

Default configuration for HTML input handling, unsafe links, and heading permalinks. The id_prefix defaults to an empty string to match GitHub's heading id convention.

```php
return [
    'html_input' => 'escape',
    'allow_unsafe_links' => false,
    'heading_permalink' => [
        'symbol' => '#',
        'html_class' => 'md-anchor',
        'id_prefix' => '',
    ],
];
```

--------------------------------

### Basic usage of Markdown::render()

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Renders a simple Markdown string to HTML. The output contains the expected heading and strong tags.

```php
use JeffersonGoncalves\Markdown\Markdown;

$html = Markdown::render('# Hello **world**');

// $html contains: <h1>Hello <strong>world</strong></h1>
```

--------------------------------

### Render untrusted user input with default config

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Shows that with default configuration, raw HTML like <script> is escaped to visible text, making the output safe to echo directly.

```php
$html = Markdown::render($userSubmittedMarkdown, headingPermalinks: true);
// With default config, raw HTML such as <script> in $userSubmittedMarkdown has been
// escaped to visible text — safe to echo without further sanitising.
```

--------------------------------

### configurePackage behavior chain

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Sets the package name to 'laravel-markdown' and registers the config file via hasConfigFile().

```php
$package
    ->name('laravel-markdown')
    ->hasConfigFile();
```

--------------------------------

### Markdown::flush() method signature

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Public static method that drops memoized caches (converters and highlighter) so the next render() rebuilds from current configuration. Returns void and takes no parameters.

```php
public static function flush(): void
```

--------------------------------

### Markdown::render() with $options

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/configuration.md

Renders Markdown to HTML with per-call options that override configuration for that call only. The $options array accepts keys like html_input, allow_unsafe_links, and heading_permalink.

```APIDOC
## [POST] Markdown::render()

### Description
Renders Markdown content to HTML. Accepts an optional $options array to override configuration for this call only.

### Method
POST (conceptual)

### Endpoint
Markdown::render($markdown, $options = [])

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **markdown** (string) - Required - The Markdown content to render.
- **options** (array) - Optional - Per-call options. Keys:
  - `html_input` (string) - Optional - 'escape', 'allow', or 'strip'. Overrides config('markdown.html_input').
  - `allow_unsafe_links` (bool) - Optional - Overrides config('markdown.allow_unsafe_links').
  - `heading_permalink` (array) - Optional - Keys: `symbol`, `html_class`, `id_prefix`. Only used when headingPermalinks is true.

### Request Example
```php
use JeffersonGoncalves\Markdown\Markdown;

$html = Markdown::render($trustedBody, options: ['html_input' => 'allow']);
```

### Response
#### Success Response (200)
- **html** (string) - The rendered HTML.

#### Response Example
```html
<div>hi</div>
```

```

--------------------------------

### Markdown::flush()

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Drops both memoized caches (the static $converters array and the static $highlighter instance) so the next render() call rebuilds the Environment, extensions, highlighter, and converter from the current configuration. Useful when the markdown.* config changes at runtime, such as in tests.

```APIDOC
## Markdown::flush()

### Description
Drops both memoized caches — the static `$converters` array and the single static `$highlighter` instance — so the next `render()` call rebuilds the Environment, extensions, highlighter and converter from the then-current configuration. Useful when the `markdown.*` config changes at runtime (e.g., in tests). After flushing, the next `render()` picks up the new config.

### Method
`flush`

### Signature
```php
public static function flush(): void
```

### Parameters
No parameters.

### Return Type
`void`

### Example — flushing after a runtime config change
```php
use JeffersonGoncalves\Markdown\Markdown;

Markdown::render('# warm up');           // builds and caches the converter

config()->set('markdown.html_input', 'allow');
Markdown::flush();                        // drop caches

$html = Markdown::render('<div>hi</div>'); // now preserves the <div>
```
```

--------------------------------

### Facade docblock declaring render method

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

The @method annotation that declares the forwarded render() method signature for IDE support.

```php
/**
 * @method static string render(string $markdown, bool $headingPermalinks = false, array $options = [])
 */
```

--------------------------------

### Forwarded render() method signature

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

The API signature callers use to render Markdown to HTML via the facade.

```php
Markdown::render(string $markdown, bool $headingPermalinks = false, array $options = []): string
```

--------------------------------

### Markdown::render()

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

Renders Markdown to HTML via the MarkdownRenderer instance resolved from the Laravel container. This is the primary method exposed by the facade for converting Markdown source text into HTML output.

```APIDOC
## Markdown::render()

### Description
Renders Markdown to HTML via the MarkdownRenderer instance resolved from the Laravel container. This is the primary method exposed by the facade for converting Markdown source text into HTML output.

### Method
render (static, forwarded)

### Signature
`Markdown::render(string $markdown, bool $headingPermalinks = false, array $options = []): string`

### Parameters
- **$markdown** (string) - Required - The Markdown source text to convert to HTML.
- **$headingPermalinks** (bool) - Optional (default: `false`) - Enables heading permalinks when `true`.
- **$options** (array<string, mixed>) - Optional (default: `[]`) - Per-call config overrides (`html_input`, `allow_unsafe_links`, `heading_permalink`).

### Return Type
string - rendered HTML.

### Example - basic usage
```php
use JeffersonGoncalves\Markdown\Facades\Markdown;

$html = Markdown::render('# Hello **world**');
// <h1>Hello <strong>world</strong></h1>
```

### Example - heading permalinks and per-call options
```php
use JeffersonGoncalves\Markdown\Facades\Markdown;

$html = Markdown::render($readme, headingPermalinks: true);
$html = Markdown::render($trustedMarkdown, options: ['html_input' => 'allow']);
```

### Example - mocking the facade in application code
```php
use JeffersonGoncalves\Markdown\Facades\Markdown;

// Swap the underlying renderer ahead of a controller test:
Markdown::shouldReceive('render')
    ->once()
    ->with('# Hello', false, [])
    ->andReturn('<h1>Hello</h1>');
```
```

--------------------------------

### Render a GitHub Flavored Markdown table

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Passes a Markdown table string to render(). The output includes <table>, <thead>, and <th>Name</th> elements.

```php
$markdown = <<<'MD'
| Name | Role |
| ---- | ---- |
| Jeff | Dev  |
MD;

$html = Markdown::render($markdown); // contains <table>, <thead>, <th>Name</th>, ...
```

--------------------------------

### Import MarkdownServiceProvider

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Imports the service provider class for use in application code.

```php
use JeffersonGoncalves\Markdown\MarkdownServiceProvider;
```

--------------------------------

### render() method signature

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-renderer.md

Full signature of the render() method from src/MarkdownRenderer.php, line 15.

```php
public function render(string $markdown, bool $headingPermalinks = false, array $options = []): string
```

--------------------------------

### Server-Side Code Highlighting

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/README.md

Fenced code blocks are highlighted server-side and emit class-based tokens. The output includes <pre><code> with span elements carrying hl-* classes. Add matching .hl-* styles to your CSS.

```php
$html = Markdown::render(<<<'MD'
```php
echo 'hello';
```
MD);
// => <pre><code>…<span class="hl-keyword">echo</span>…</code></pre>
```

--------------------------------

### MarkdownRenderer::render() with $options

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/configuration.md

Renders Markdown to HTML using the MarkdownRenderer class, with the same per-call options as the static Markdown::render().

```APIDOC
## [POST] MarkdownRenderer::render()

### Description
Renders Markdown content to HTML. Accepts an optional $options array to override configuration for this call only.

### Method
POST (conceptual)

### Endpoint
MarkdownRenderer::render($markdown, $options = [])

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **markdown** (string) - Required - The Markdown content to render.
- **options** (array) - Optional - Per-call options. Keys:
  - `html_input` (string) - Optional - 'escape', 'allow', or 'strip'. Overrides config('markdown.html_input').
  - `allow_unsafe_links` (bool) - Optional - Overrides config('markdown.allow_unsafe_links').
  - `heading_permalink` (array) - Optional - Keys: `symbol`, `html_class`, `id_prefix`. Only used when headingPermalinks is true.

### Request Example
```php
$renderer = new MarkdownRenderer();
$html = $renderer->render($markdown, options: ['html_input' => 'allow']);
```

### Response
#### Success Response (200)
- **html** (string) - The rendered HTML.

#### Response Example
```html
<div>hi</div>
```

```

--------------------------------

### packageBooted method signature

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Declares the packageBooted method that registers the @markdown Blade directive.

```php
public function packageBooted(): void
```

--------------------------------

### Facade accessor method signature

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-facade.md

The protected method that returns the container key for the underlying MarkdownRenderer instance.

```php
protected static function getFacadeAccessor(): string
```

--------------------------------

### Markdown::render() method signature

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Full signature of the static render method. Returns a string of rendered HTML. No exceptions are declared or caught inside the method.

```php
public static function render(string $markdown, bool $headingPermalinks = false, array $options = []): string
```

--------------------------------

### Render with heading permalinks

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Enables heading permalinks by passing headingPermalinks: true. Adds an md-anchor anchor and GitHub-style id attributes to headings.

```php
// Adds <a class="md-anchor">…</a> inside every heading; ids are GitHub-style (id="{slug}"):
$html = Markdown::render('# Installation', headingPermalinks: true);
// heading carries id="installation" and an md-anchor anchor
```

--------------------------------

### render()

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-renderer.md

Renders Markdown source text to HTML. This method is the primary API for converting Markdown to HTML, with optional heading permalinks and per-call configuration overrides.

```APIDOC
## render()

### Description
Renders Markdown source text to HTML. This method is the primary API for converting Markdown to HTML, with optional heading permalinks and per-call configuration overrides.

### Method
`render`

### Signature
```php
public function render(string $markdown, bool $headingPermalinks = false, array $options = []): string
```

### Parameters
- **$markdown** (string) - Required - The Markdown source text to convert to HTML.
- **$headingPermalinks** (bool) - Optional - Default: `false` - Enables heading permalink anchors when `true`.
- **$options** (array<string, mixed>) - Optional - Default: `[]` - Per-call overrides of the config keys (`html_input`, `allow_unsafe_links`, `heading_permalink`).

### Return Type
`string` - The rendered HTML, produced by delegating to `Markdown::render($markdown, $headingPermalinks, $options)`. All behavior (GFM features, syntax highlighting, escaping, memoization) is identical to the static API.

### Throws
Delegates directly; no exceptions are declared or caught in this method. See the notes under `Markdown::render()` in markdown.md.

### Example - Basic Usage
```php
use JeffersonGoncalves\Markdown\MarkdownRenderer;

$renderer = new MarkdownRenderer;
$html = $renderer->render('# Hello **world**');
// $html contains <h1>Hello <strong>world</strong></h1>
```

### Example - With Heading Permalinks and Per-Call Options
```php
$renderer = app(MarkdownRenderer::class);

$html = $renderer->render($readme, headingPermalinks: true);
// headings get an <a class="md-anchor"> and GitHub-style id="{slug}" (see configuration.md)

$html = $renderer->render($trustedBody, options: ['html_input' => 'allow']);
// this call only preserves raw HTML; the stored config is untouched
```

### Example - Error Handling / Safety Consideration
Because the class only forwards to the static engine, exceptions (from `league/commonmark` or `tempest/highlight`) propagate unchanged. When rendering untrusted input, keep the default configuration so the output remains safe; for `html_input => 'allow'` output, sanitize the HTML before display:

```php
use JeffersonGoncalves\Markdown\MarkdownRenderer;

try {
    $html = (new MarkdownRenderer)->render($userInput, headingPermalinks: true);
    // default config => raw HTML escaped, safe to echo
} catch (\Throwable $e) {
    // no package-specific exception; any failure bubbles up from the
    // underlying CommonMark/tempest-highlight stack
    report($e);
}
```
```

--------------------------------

### Render trusted content with raw HTML and per-call overrides

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Uses the options parameter to allow raw HTML for a single call. The override affects only this call and does not mutate stored config.

```php
// Trusted README whose inline HTML must be preserved. Affects this call only:
$html = Markdown::render($readme, options: ['html_input' => 'allow']);

// Same effect, but globally via config — see configuration.md.
```

--------------------------------

### composer.json auto-discovery providers entry

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Registers the service provider for Laravel auto-discovery via the extra.laravel.providers key in composer.json.

```json
"extra": {
    "laravel": {
        "providers": [
            "JeffersonGoncalves\\Markdown\\MarkdownServiceProvider"
        ]
    }
}
```

--------------------------------

### @markdown($source)

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Renders Markdown source to HTML and echoes it directly. This is the base form with no heading permalinks.

```APIDOC
## @markdown($source)

### Description
Renders the given Markdown source to HTML and echoes it directly. This is the base form with no heading permalinks.

### Usage
In a Blade template, use:

```blade
@markdown($source)
```

### Parameters
- `$source` (string) - Required - The Markdown source. Any valid PHP expression for the `$markdown` parameter of `Markdown::render()`.

### Output
Echoes the rendered HTML string directly. Does not return a value.

### Example
```blade
@markdown('# Hello **world**')
{{-- echoes <h1>Hello <strong>world</strong></h1> ---}}
```
```

--------------------------------

### Import MarkdownRenderer class

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-renderer.md

Import statement for the MarkdownRenderer class.

```php
use JeffersonGoncalves\Markdown\MarkdownRenderer;
```

--------------------------------

### Compiled output of @markdown directive

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Shows the PHP code generated by the Blade directive for a given expression.

```php
<?php echo \JeffersonGoncalves\Markdown\Markdown::render({$expression}); ?>
```

--------------------------------

### Using @markdown in Blade templates

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Echoes rendered HTML, optionally with heading permalinks when passing true as the second argument.

```blade
{{-- Blade template ---}}
@markdown($articleBody)
{{-- echoes the rendered HTML ---}}

@markdown($articleBody, true)
{{-- echoes the rendered HTML with heading permalinks ---}}
```

--------------------------------

### @markdown($source, true)

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Renders Markdown source to HTML with heading permalinks enabled and echoes it directly. Equivalent to `Markdown::render($source, true)`.

```APIDOC
## @markdown($source, true)

### Description
Renders the given Markdown source to HTML with heading permalinks enabled and echoes it directly. Equivalent to `Markdown::render($source, true)`.

### Usage
In a Blade template, use:

```blade
@markdown($source, true)
```

### Parameters
- `$source` (string) - Required - The Markdown source.
- `true` (bool) - Required - Enables heading permalinks.

### Output
Echoes the rendered HTML string directly. Does not return a value.

### Example
```blade
@markdown($readme, true)
{{-- echoes headings carrying an <a class="md-anchor"> and GitHub-style id="{slug}" ---}}
```
```

--------------------------------

### Partial heading_permalink override with id_prefix only

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/configuration.md

Overrides only the id_prefix subkey; unspecified subkeys fall back to config then hard-coded defaults. The comment shows that symbol stays '#' and html_class stays 'md-anchor'.

```php
$html = Markdown::render('# Installation', headingPermalinks: true, options: [
    'heading_permalink' => ['id_prefix' => 'content'],
]);
// symbol stays '#', html_class stays 'md-anchor', id becomes content-installation
```

--------------------------------

### @markdown($source, options: ['html_input' => 'allow'])

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Renders Markdown source to HTML with custom options using named arguments. Equivalent to `Markdown::render($source, options: ['html_input' => 'allow'])`.

```APIDOC
## @markdown($source, options: ['html_input' => 'allow'])

### Description
Renders the given Markdown source to HTML with custom options using named arguments. Equivalent to `Markdown::render($source, options: ['html_input' => 'allow'])`.

### Usage
In a Blade template, use:

```blade
@markdown($source, options: ['html_input' => 'allow'])
```

### Parameters
- `$source` (string) - Required - The Markdown source.
- `options` (array) - Required - Options to pass to the renderer.

### Output
Echoes the rendered HTML string directly. Does not return a value.

### Example
```blade
@markdown($source, options: ['html_input' => 'allow'])
```
```

--------------------------------

### Per-call heading_permalink override with symbol, html_class, id_prefix

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/configuration.md

Overrides heading_permalink subkeys for a single render call when headingPermalinks is true. The id_prefix affects the generated anchor id, e.g., id="content-installation".

```php
$html = Markdown::render('# Installation', headingPermalinks: true, options: [
    'heading_permalink' => [
        'symbol' => '★',
        'html_class' => 'my-anchor',
        'id_prefix' => 'content',   // -> id="content-installation"
    ],
]);
```

--------------------------------

### @markdown($source, headingPermalinks: true)

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Renders Markdown source to HTML with heading permalinks enabled using named arguments. Equivalent to `Markdown::render($source, headingPermalinks: true)`.

```APIDOC
## @markdown($source, headingPermalinks: true)

### Description
Renders the given Markdown source to HTML with heading permalinks enabled using named arguments. Equivalent to `Markdown::render($source, headingPermalinks: true)`.

### Usage
In a Blade template, use:

```blade
@markdown($source, headingPermalinks: true)
```

### Parameters
- `$source` (string) - Required - The Markdown source.
- `headingPermalinks` (bool) - Required - Enables heading permalinks.

### Output
Echoes the rendered HTML string directly. Does not return a value.

### Example
```blade
@markdown($source, headingPermalinks: true)
```
```

--------------------------------

### Named-argument form of @markdown

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

PHP named arguments work because the expression is interpolated verbatim. Use headingPermalinks or options for clarity.

```blade
@markdown($source, headingPermalinks: true)
```

```blade
@markdown($source, options: ['html_input' => 'allow'])
```

--------------------------------

### Per-call html_input override with Markdown::render

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/configuration.md

Overrides the html_input option for a single render call without modifying the config file. The default escape behavior is preserved for subsequent calls, as shown by the second render call that still escapes HTML.

```php
use JeffersonGoncalves\Markdown\Markdown;

// Trusted content only: keep raw HTML for THIS call
$html = Markdown::render($trustedBody, options: ['html_input' => 'allow']);

// Still escapes afterwards because config was never modified
$html = Markdown::render('<div>hi</div>'); // => &lt;div&gt;hi&lt;/div&gt;
```

--------------------------------

### @markdown with heading permalinks

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Enables heading permalinks, adding an anchor link and GitHub-style id to headings.

```blade
@markdown($readme, true)
{{-- echoes headings carrying an <a class="md-anchor"> and GitHub-style id="{slug}" ---}}
```

--------------------------------

### @markdown($source, true) permalink form

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Enables heading permalinks by passing true as the second argument. Equivalent to Markdown::render($source, true).

```blade
@markdown($source, true)
```

--------------------------------

### Register @markdown Blade directive

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown-service-provider.md

Registers the Blade directive that renders markdown via the Markdown facade.

```php
Blade::directive('markdown', function (string $expression): string {
    return "<?php echo \JeffersonGoncalves\Markdown\Markdown::render({$expression}); ?>";
});
```

--------------------------------

### @markdown($source) base form

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Renders Markdown with default options (headingPermalinks: false). Equivalent to Markdown::render($source).

```blade
@markdown($source)
```

--------------------------------

### Import the Markdown class

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/markdown.md

Import the fully static Markdown class from the JeffersonGoncalves\Markdown namespace. The class converts CommonMark/GitHub Flavored Markdown to HTML with server-side syntax highlighting and is used by the MarkdownRenderer, Laravel facade, and Blade directive.

```php
use JeffersonGoncalves\Markdown\Markdown;
```

--------------------------------

### Compiled output of @markdown directive

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Shows the PHP code the directive compiles to in a Blade template. The expression is inserted raw, so any valid PHP expression works.

```php
<?php echo \JeffersonGoncalves\Markdown\Markdown::render(<expression>); ?>
```

--------------------------------

### @markdown inside @if condition

Source: https://github.com/jeffersongoncalves/laravel-markdown/blob/main/_autodocs/api-reference/blade-directive.md

Shows the directive coexisting with raw PHP in Blade. The directive only renders when the condition is true.

```blade
@if ($showReadme)
    @markdown($readme, true)
@endif
```
Tokens:
Raw