README

Marklink

一个简单的标准，允许在 Markdown 文件中嵌入（并解析）分类链接列表。

Marklink 最初是为了尝试标准化 GitHub 上可用的各种 链接精彩列表 而产生的。

架构

每个包含嵌入良好格式 Marklink 部分的 Markdown 文档都可以被 Marklink 解析器解析成具有分类和链接的树状 JSON 结构。这个 JSON 数据结构由架构文件描述（参考 marklink.schema.json）。架构文件允许验证 JSON 结构（参考 JSON Schema）。

架构规则

1. 有两种类型的节点
   • 分类
   • 链接
2. 有四种类型的节点字段（除确定节点类型的 type 字段外）
   • 标题
   • URL
   • 描述
   • 子节点
3. 只有一个根 category 节点
4. 根节点下的 category 节点 需要有效的 title，并可以包含其他字段（可选）
5. category 节点 可以有子 category 节点 或 link 节点 - 但不能同时混合
6. link 节点 需要有效的 title 和有效的 url，可以有子 link 节点，但不能有子 category 节点

示例

下面是一些示例，说明如何通过 Marklink 解析器将 Markdown 片段解析成 JSON 数据（更多示例请参阅 tests/ 目录）。

基本示例

输入

- [Link A](http://a.example.com) - Link A description
- [Link B](http://b.example.com) - Link B description with [link](http://link.example.com)

输出

{
    "type": "category",
    "children": [
        {
            "type": "link",
            "title": "Link A",
            "url": "http://a.example.com",
            "description": "Link A description"
        },
        {
            "type": "link",
            "title": "Link B",
            "url": "http://b.example.com",
            "description": "Link B description with [link](http://link.example.com)"
        }
    ]
}

高级示例

输入

## Category A

Category A description

### Sub-category A

- Sub-sub-category A
    - [Link A](http://a.example.com) - Link A description
    - [Link B](http://b.example.com) - Link B description with [link](http://link.example.com)
        - [Link C](http://c.example.com) - Link C description

输出

{
    "type": "category",
    "children": [
        {
            "type": "category",
            "title": "Category A",
            "description": "Category A description",
            "children": [
                {
                    "type": "category",
                    "title": "Sub-category A",
                    "children": [
                        {
                            "type": "category",
                            "title": "Sub-sub-category A",
                            "children": [
                                {
                                    "type": "link",
                                    "title": "Link A",
                                    "url": "http://a.example.com",
                                    "description": "Link A description"
                                },
                                {
                                    "type": "link",
                                    "title": "Link B",
                                    "url": "http://b.example.com",
                                    "description": "Link B description with [link](http://link.example.com)",
                                    "children": [
                                        {
                                            "type": "link",
                                            "title": "Link C",
                                            "url": "http://c.example.com",
                                            "description": "Link C description",
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

带有标记的输入

默认情况下，Marklink 解析器将解析整个文档，除非它找到以下标记

<!-- marklink:start -->
- [Link A](http://a.example.com) - Link A description
- [Link B](http://b.example.com) - Link B description with [link](http://link.example.com)
<!-- marklink:end -->

在这种情况下，只有标记之间的内容将被解析。

在线 Marklink 解析服务

Markling 解析器的初始实现可作为一项服务提供。

网页界面

https://awesomelist.kminek.pl/marklink

cURL 示例

curl --request POST \
  --url https://awesomelist.kminek.pl/api/markdown \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{"input": "- [Link A](http://a.example.com) - Link A description\n- [Link B](http://b.example.com) - Link B description with [link](http://link.example.com)"}'

PHP 示例

composer require kminek/marklink

use Kminek\Marklink\ParserService;

$markdown = <<<MARKDOWN
- [Link A](http://a.example.com) - Link A description
- [Link B](http://b.example.com) - Link B description with [link](http://link.example.com)
MARKDOWN;

$parser = new ParserService;
$result = $parser->parse($markdown);