README

Markdown Builder

Markdown 辅助类，用于创建 Markdown。

此 README.md 由该库生成，详情请查看 bin/readme.php。

安装

composer require premier/markdown-builder

使用方法

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

Markdown Builder 有两种元素：块元素和行内元素。块元素将被缓冲，如果你调用 getMarkdown() 方法，你将得到 Markdown。所有行内元素将立即获得 Markdown 输出。

块元素

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

引用块

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

> Foo
> Bar
> Baz

水平线

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

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

代码

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

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

徽章

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

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

无序列表

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

* Foo
* Bar
* Baz

可调用的无序列表

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

* Hallo
* foo
* bar

可调用的无序列表排序

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

有序列表

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

1. Foo
2. Bar
3. Baz

可调用的有序列表

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

1. Hallo
2. foo
3. bar

可调用的有序列表排序

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

复选框列表

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

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

可调用的复选框列表

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

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

可调用的复选框列表排序

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

表格

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

可调用的表格

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

可调用的表格排序

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

嵌套列表的表格

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>

行内块

粗体

Markdown::bold('Hey!');

**Hey!**

斜体

Markdown::italic('huhu');

*huhu*

代码

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

`$var = "test";`

链接

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

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

图片

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

![Cat](cat.jpg)

徽章

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

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

有序列表

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

1. A
2. B
3. C

无序列表

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

* A
* B
* C

复选框列表

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

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

高级功能

折叠块

如果你需要折叠块，你可以创建一个新的带有自己清洁缓冲区的构建器实例。

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

回调

如果你想从复杂逻辑或可迭代值添加块，但又不想停止链式调用，你可以使用回调。

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.

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

输出到文件

你不仅可以返回 Markdown 字符串，还可以轻松地将结果输出到文件。

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