Markdown

O recurso Markdown permite transformar strings e arquivos Markdown em HTML, tornando-o útil em diversos cenários, como a criação de blogs.

Convertendo string

Convertendo uma string contendo Markdown para HTML com parágrafos:


        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;

Saída:


          <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>

Convertendo uma string contendo Markdown para HTML sem parágrafos:


        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;

Saída:


          <em>Italic</em>

          <strong>bold</strong>

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

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

Para permitir HTML arbitrário na sintaxe do documento, deve-se utilizar o método enableHtml(), como no exemplo:


        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;

Saída:


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

Convertendo arquivos

Para converter arquivos, o método utilizado é o fromFile() (as quebras de linha serão convertidas em parágrafos <p>...</p>). Exemplo:


        use Inphinit\Experimental\Utility\Markdown;

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

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

        echo $output;

Convertendo arquivo do armazenamento:


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

        echo $output;

API

Uso	Descrição
`__construct(bool $enableCustom = true)`	Se `$enableCustom` for `true` (padrão), as seguintes sintaxes customizadas serão adicionadas: `!highlight!` -> `<mark>highlight</mark>` `%variable%` -> `<var>variable</var>` `+inserted+` -> `<ins>inserted</ins>` `-deleted-` -> `<del>deleted</del>`
`fromString(string $input): string`	Converte uma string markdown em HTML, tornando quebras de linhas em paragrafos `<p>...</p>`.
`fromInlineString(string $input): string`	Converte uma string markdown em HTML, preservando as quebras de linha.
`fromFile(string $path): string`	Converte um arquivo markdown em HTML, tornando quebras de linhas em paragrafos `<p>...</p>`.
`enableErrors(bool $enable): void`	Habilita ou desabilita erros no parser. Se habilitado, qualquer falha grave irá emitir uma exception, se desabilitado (padrão) a falha será ignorada, e a sintaxe falha será tratada como texto no HTML gerado.
`enableHtml(bool $enable): void`	Habilita ou desabilita tags HTML dentro do documento markdown. O comportamento padrão (desabilitado) transforma tags HTML no markdown e texto de entidades HTML.
`setCustomInline(string $delimiter, string $template): void`	Se necessitar criar um sintaxe própria para gerar elementos a partir de uma sintaxe inline (ou dentro de paragráfos) é possivel executar algo como `$parser->setCustomInline('@', '<div align="center">{contents}</div>');` que irá permitir algo como `Foo @sample@ bar` gerar `Foo <div align="center">sample</div> bar`.
`setTemplate(int $type, string $template): void`	Permite criar sintaxe simples para gerar elementos em um contexto inline.

Customizando saída HTML

É possivel customizar a maioria das tags HTML geradas na conversão, usando o método setTemplate() através das constantes pré-definidas:

Uso	Nota
`setTemplate(Markdown::BLOCKQUOTE, '<blockquote>{contents}</blockquote>')`
`setTemplate(Markdown::CODE_BLOCK, '<pre data-lang="{lang}"><code>{contents}</code></pre>')`	Se a sintaxe não contiver a linguagem, o valor de `{lang}` será `none`.
`setTemplate(Markdown::H1, '<h1>{contents}</h1>')`
`setTemplate(Markdown::H2, '<h2 id="{id}"><a href="#{id}">{contents}</a></h2>')`	Somente o H2 (`## heading 2`) recebe ID, e cada H2 assim como o conteudo posterior, serão movido para dentro `<section>...</section>` próprio.
`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 ao `Markdown::ANCHOR`, com a exceção que será usado somente com a sintaxe `[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 ao `Markdown::FIGURE`, com a exceção que será usado somente com a sintaxe `![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>')`