Markdown

The Markdown feature allows you to transform Markdown strings and files into HTML, making it useful in various scenarios, such as creating blogs.

Converting string

Converting a string containing Markdown to HTML with paragraphs:


        use Inphinit\Experimental\Utility\Markdown;

        $parser = new Markdown();

        $input = "*Italic*\n\n**bold**\n\n![display a forest](/images/forest.jpg)\n\n[login access](/login.html)";

        $output = $parser->fromString($input);

        echo $output;

Output:


          <p><em>Italic</em></p>
          <p><strong>bold</strong></p>
          <p><figure><img src="/images/forest.jpg" alt="forest"></figure></p>
          <p><a href="/login.html">login access</a></p>

Converting a string containing Markdown to HTML without paragraphs:


        use Inphinit\Experimental\Utility\Markdown;

        $parser = new Markdown();

        $input = "*Italic*\n\n**bold**\n\n![display a forest](/images/forest.jpg)\n\n[login access](/login.html)";

        $output = $parser->fromInlineString($input);

        echo $output;

Output:


          <em>Italic</em>

          <strong>bold</strong>

          <figure><img src="/images/forest.jpg" alt="forest"></figure>

          <a href="/login.html">login access</a>

To allow arbitrary HTML in the document syntax, the method enableHtml()should be used, as in the example:


        use Inphinit\Experimental\Utility\Markdown;

        $parser = new Markdown();
        $parser->enableHtml(true);

        $input = "**bold**\n\n<div align='center'>foo bar baz</div>\n\n<video src='video.webm'></video>";

        $output = $parser->fromString($input);

        echo $output;

Output:


          <p><strong>bold</strong></p>
          <p><div align='center'>foo bar baz</div></p>
          <p><video src='video.webm'></video></p>

Converting files

To convert files, the method used is fromFile()(line breaks will be converted into paragraphs <p>...</p>). Example:


        use Inphinit\Experimental\Utility\Markdown;

        $parser = new Markdown();
        $parser->enableHtml(true);

        $output = $parser->fromFile('/foo/bar/baz/document.md');

        echo $output;

Converting a file from storage:


        $output = $parser->fromFile(INPHINIT_SYSTEM . '/storage/document.md');

        echo $output;

API

Use	Description
`__construct(bool $enableCustom = true)`	If `$enableCustom`it is `true`(default), the following custom syntaxes will be added: `!highlight!`->`<mark>highlight</mark>` `%variable%`->`<var>variable</var>` `+inserted+`->`<ins>inserted</ins>` `-deleted-`->`<del>deleted</del>`
`fromString(string $input): string`	Converts a markdown string to HTML, turning line breaks into paragraphs `<p>...</p>`.
`fromInlineString(string $input): string`	Converts a markdown string to HTML while preserving line breaks.
`fromFile(string $path): string`	Converts a markdown file to HTML, turning line breaks into paragraphs `<p>...</p>`.
`enableErrors(bool $enable): void`	Enables or disables errors in the parser. If enabled, any serious error will throw an exception; if disabled (default), the error will be ignored, and the faulty syntax will be treated as text in the generated HTML.
`enableHtml(bool $enable): void`	Enables or disables HTML tags within the markdown document. The default behavior (disabled) transforms HTML tags into markdown and HTML entity text.
`setCustomInline(string $delimiter, string $template): void`	If you need to create your own syntax to generate elements from inline syntax (or within paragraphs), you can execute something like this `$parser->setCustomInline('@', '<div align="center">{contents}</div>');`, which will allow you `Foo @sample@ bar`to generate elements from inline syntax `Foo <div align="center">sample</div> bar`.
`setTemplate(int $type, string $template): void`	It allows you to create simple syntax for generating elements in an inline context.

Customizing HTML output

It is possible to customize most of the HTML tags generated during conversion using the method setTemplate()via predefined constants:

Use	Notice
`setTemplate(Markdown::BLOCKQUOTE, '<blockquote>{contents}</blockquote>')`
`setTemplate(Markdown::CODE_BLOCK, '<pre data-lang="{lang}"><code>{contents}</code></pre>')`	If the syntax does not contain the language, the value of `{lang}`will be `none`.
`setTemplate(Markdown::H1, '<h1>{contents}</h1>')`
`setTemplate(Markdown::H2, '<h2 id="{id}"><a href="#{id}">{contents}</a></h2>')`	Only the H2 ( `## heading 2`) receives an ID, and each H2, as well as the subsequent content, will be moved within `<section>...</section>`its own.
`setTemplate(Markdown::H3, '<h3>{contents}</h3>')`
`setTemplate(Markdown::H4, '<h4>{contents}</h4>')`
`setTemplate(Markdown::H5, '<h5>{contents}</h5>')`
`setTemplate(Markdown::H6, '<h6>{contents}</h6>')`
`setTemplate(Markdown::HR, '<hr>')`
`setTemplate(Markdown::ANCHOR, '<a href="{url}">{contents}</a>')`
`setTemplate(Markdown::ANCHOR_TITLE, '<a href="{url}" title="{title}">{contents}</a>')`	Similar to `Markdown::ANCHOR`, except that it will only be used with the syntax `[contents](url "title")`.
`setTemplate(Markdown::FIGURE, '<figure><img src="{url}" alt="{alternative}"></figure>')`
`setTemplate(Markdown::FIGURE_CAPTION, '<figure><img src="{url}" alt="{alternative}"><figcaption>{title}</figcaption></figure>')`	Similar to `Markdown::FIGURE`, except that it will only be used with the syntax `![alt](url "caption")`.
`setTemplate(Markdown::OL, '<ol>{contents}</ol>')`
`setTemplate(Markdown::UL, '<ul>{contents}</ul>')`
`setTemplate(Markdown::BOLD, '<strong>{contents}</strong>')`
`setTemplate(Markdown::CODE, '<code>{contents}</code>')`
`setTemplate(Markdown::ITALIC, '<em>{contents}</em>')`
`setTemplate(Markdown::STRIKETHROUGH, '<s>{contents}</s>')`
`setTemplate(Markdown::TABLE, '<table><thead><tr>{headers}</tr></thead><tbody>{contents}</tbody></table>')`
`setTemplate(Markdown::SUBSCRIPT, '<sub>{contents}</sub>')`
`setTemplate(Markdown::SUPERSCRIPT, '<sup>{contents}</sup>')`

Usage:


        use Inphinit\Experimental\Utility\Markdown;

        $parser = new Markdown();

        // Lazy loading
        $parser->setTemplate(Markdown::FIGURE, '<img src="{url}" alt="{alternative}" loading="lazy">');

        // class attribute
        $parser->setTemplate(Markdown::UL, '<ul class="foo-bar">{contents}</ul>');

        $output = $parser->fromFile('/foo/bar/baz/document.md');

        echo $output;