Markdown Builder

A helper class to create markdown.

This README.md generated by this library, check bin/readme.php for details.

Installation

composer require premier/markdown-builder

Usage

Markdown::builder()
    ->h1('Markdown Builder')
    ->p('A helper class to create markdown.')
    ->h2('Install '.Markdown::bold('this').' powerfull library')
    ->code('composer require premier/markdown-builder', 'bash')
    ->h2('Todos')
    ->checklist([
        [true, 'write tests'],
        [true, Markdown::numberedList(['TableBuilder', 'ListBuilders', 'Checklist'])],
        [false, 'add more markdown features'],
        [true, 'Configure CI'],
        [false, 'CI readme check'],
    ])
    ->getMarkdown();

Markdown Builder
================

A helper class to create markdown.

Install **this** powerfull library
----------------------------------

```bash
composer require premier/markdown-builder
```

Todos
-----

- [X] write tests
- [X] 1. TableBuilder
      2. ListBuilders
      3. Checklist
- [ ] add more markdown features
- [X] Configure CI
- [ ] CI readme check

API

The markdown builder have two kinds of elements, block and inline elements. Block elements will be buffered and you can get the markdown if you call the method getMarkdown(). All inline Elements get instantly the markdown output.

Block Elements

h1

Markdown::builder()->h1('Hello H1');

Hello H1
========

h2

Markdown::builder()->h2('Hello H2');

Hello H2
--------

h3

Markdown::builder()->h3('Hello H3');

### Hello H3

h4

Markdown::builder()->h4('Hello H4');

#### Hello H4

h5

Markdown::builder()->h5('Hello H5');

##### Hello H5

h6

Markdown::builder()->h6('Hello H6');

###### Hello H6

p

Markdown::builder()->p('paragraph');

paragraph

Blockquote

Markdown::builder()->blockquote("Foo\nBar\nBaz");

> Foo
> Bar
> Baz

hr

Markdown::builder()->hr();

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

Code

Markdown::builder()->code('$var = "test";', 'php');

```php
$var = "test";
```

Badge

Markdown::builder()->badge(
    'Latest Stable Version',
    'https://poser.pugx.org/premier/markdown-builder/v',
    '//packagist.org/packages/premier/markdown-builder',
);

[![Latest Stable Version](https://poser.pugx.org/premier/markdown-builder/v)](//packagist.org/packages/premier/markdown-builder)

Bulleted list

Markdown::builder()->bulletedList(['Foo', 'Bar', 'Baz']);

* Foo
* Bar
* Baz

Bulleted list callable

Markdown::builder()->bulletedList(static function (BulletedListBuilder $builder): void {
    $builder
        ->addLine('Hallo')
        ->addLine('foo')
        ->addLine('bar');
});

* Hallo
* foo
* bar

Bulleted list callable sort

Markdown::builder()->bulletedList(static function (BulletedListBuilder $builder): void {
    $builder
        ->addLine('C')
        ->addLine('A')
        ->addLine('B')
        ->addLine('D')
        ->sort(fn (string $left, string $right) => $left <=> $right);
});

* A
* B
* C
* D

Numbered list

Markdown::builder()->numberedList(['Foo', 'Bar', 'Baz']);

1. Foo
2. Bar
3. Baz

Numbered list callable

Markdown::builder()->numberedList(static function (NumberedListBuilder $builder) {
    $builder
        ->addLine('Hallo')
        ->addLine('foo')
        ->addLine('bar');
});

1. Hallo
2. foo
3. bar

Numbered list callable sort

Markdown::builder()->numberedList(static function (NumberedListBuilder $builder) {
    $builder
        ->addLine('A')
        ->addLine('D')
        ->addLine('B')
        ->addLine('C')
        ->sort(fn (string $left, string $right) => $left <=> $right);
});

1. A
2. B
3. C
4. D

Checklist

Markdown::builder()->checklist([
    [false, 'Hallo'],
    [false, 'foo'],
    [true, 'bar'],
]);

- [ ] Hallo
- [ ] foo
- [X] bar

Checklist callable

Markdown::builder()->checklist(static function (ChecklistBuilder $builder): void {
    $builder
        ->addLine(false, 'Hallo')
        ->addLine(false, 'foo')
        ->addLine(true, 'bar');
});

- [ ] Hallo
- [ ] foo
- [X] bar

Checklist callable sort

Markdown::builder()->checklist(static function (ChecklistBuilder $builder): void {
    $builder
        ->addLine(false, 'C')
        ->addLine(false, 'D')
        ->addLine(true, 'B')
        ->addLine(true, 'A')
        ->sort(fn (array $left, array $right) => $left[1] <=> $right[1]);
});

- [X] A
- [X] B
- [ ] C
- [ ] D

Table

Markdown::builder()->table(
    ['First Header', 'Second Header'],
    [
        ['Content from cell 1', 'Content from cell 2'],
        ['Content in the first column', 'Content in the second column'],
    ]
);

First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second column

Table callable

Markdown::builder()->table(
    ['First Header', 'Second Header'],
    static function (TableBuilder $builder): void {
        $builder
            ->addRow('Content from cell 1', 'Content from cell 2')
            ->addRow('Content in the first column', 'Content in the second column');
    },
);

First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second column

Table callable sort

Markdown::builder()->table(
    ['First Header', 'Second Header'],
    static function (TableBuilder $builder): void {
        $builder
            ->addRow('C', 'Content from cell C')
            ->addRow('A', 'Content from cell A')
            ->addRow('B', 'Content from cell B')
            ->sort(fn (array $left, array $right) => $left[0] <=> $right[0]);
    },
);

First Header | Second Header
------------ | -------------
A | Content from cell A
B | Content from cell B
C | Content from cell C

Table with nested list

Markdown::builder()->table(
    ['First Header', 'Second Header'],
    static function (TableBuilder $builder): void {
        $builder
            ->addRow('A', Markdown::listAsHtml(Markdown::checklist([
                [true, 'A'],
                [false, 'B'],
                [false, 'C'],
            ])))
            ->addRow('B', Markdown::listAsHtml(Markdown::checklist([
                [true, 'D'],
                [false, 'E'],
                [false, 'F'],
            ])));
    },
);

First Header | Second Header
------------ | -------------
A | <ul><li>- [X] A</li><li>- [ ] B</li><li>- [ ] C</li></ul>
B | <ul><li>- [X] D</li><li>- [ ] E</li><li>- [ ] F</li></ul>

Inline Blocks

Bold

Markdown::bold('Hey!');

**Hey!**

Italic

Markdown::italic('huhu');

*huhu*

Code

Markdown::code('$var = "test";');

`$var = "test";`

Link

Markdown::link('https://google.com', 'Google');

[Google](https://google.com)

img

Markdown::img('cat.jpg', 'Cat');

![Cat](cat.jpg)

Badge

Markdown::badge(
    'Latest Stable Version',
    'https://poser.pugx.org/premier/markdown-builder/v',
    '//packagist.org/packages/premier/markdown-builder',
    );

[![Latest Stable Version](https://poser.pugx.org/premier/markdown-builder/v)](//packagist.org/packages/premier/markdown-builder)

Numbered list

Markdown::numberedList(['A', 'B', 'C']);

1. A
2. B
3. C

Bulleted list

Markdown::bulletedList(['A', 'B', 'C']);

* A
* B
* C

Checklist

Markdown::checklist([
    [true, 'A'],
    [true, 'B'],
    [false, 'C'],
]);

- [X] A
- [X] B
- [ ] C

Advanced Features

Collapse block

if you need collapse blocks, you can create a new builder instance with his own clean buffer.

Markdown::builder()
    ->blockquote(
        Markdown::builder()
          ->h1('Lists')
          ->bulletedList([
            'Foo',
            Markdown::numberedList(['A', 'B', 'C']),
            'Bar'
          ])->getMarkdown()
    )
    ->getMarkdown();

> Lists
> =====
>
> * Foo
> * 1. A
>   2. B
>   3. C
> * Bar

Callback

If you want to add blocks from complex logic or iterable value, but don't want to stop chain calls you can use callback.

Markdown::builder()
    ->p('Callback Example')
    ->callback(static function (Builder $builder) {
        foreach ([1, 2, 3] as $item) {
            $builder
                ->p($item.' paragraph.')
                ->hr();
        }
    })
    ->getMarkdown();

Callback Example

1 paragraph.

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

2 paragraph.

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

3 paragraph.

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

Dump to File

Instead of returning markdown as a string you can easy dump result to file.

Markdown::builder()->h1('Hello world!')->dump('index.md');