PHPackages                             kminek/marklink - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. kminek/marklink

ActiveLibrary[Parsing & Serialization](/categories/parsing)

kminek/marklink
===============

A simple standard allowing embedding (and parsing) categorized lists of links inside Markdown files.

v1.0.0(5y ago)533[2 PRs](https://github.com/kminek/marklink/pulls)PHPPHP >=8.0.0

Since Mar 19Pushed 3y ago2 watchersCompare

[ Source](https://github.com/kminek/marklink)[ Packagist](https://packagist.org/packages/kminek/marklink)[ RSS](/packages/kminek-marklink/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (1)Dependencies (8)Versions (4)Used By (0)

[![Marklink logo](https://camo.githubusercontent.com/a88fa5229bb33c057caa5fb51d4e6ca5dbd505973c19d12c6ed16e1b09cc3c36/68747470733a2f2f63646e2e7261776769742e636f6d2f6b6d696e656b2f6d61726b6c696e6b2f6d61737465722f6d656469612f6d61726b6c696e6b2e6c6f676f2e737667)](https://camo.githubusercontent.com/a88fa5229bb33c057caa5fb51d4e6ca5dbd505973c19d12c6ed16e1b09cc3c36/68747470733a2f2f63646e2e7261776769742e636f6d2f6b6d696e656b2f6d61726b6c696e6b2f6d61737465722f6d656469612f6d61726b6c696e6b2e6c6f676f2e737667)

Marklink
========

[](#marklink)

A simple standard allowing embedding (and parsing) categorized lists of links inside [Markdown](https://en.wikipedia.org/wiki/Markdown) files.

Marklink was born as an attempt to standardize various [awesome lists of links](https://github.com/sindresorhus/awesome) available on GitHub.

Schema
------

[](#schema)

Every Markdown document with embedded well-formed Marklink sections can be parsed by Marklink parser into tree-like [JSON](https://en.wikipedia.org/wiki/JSON)structure with categories and links. This JSON data structure is described by schema file (see [marklink.schema.json](https://raw.githubusercontent.com/kminek/marklink/master/marklink.schema.json) for reference). Schema file allows JSON structure to be validated (see [JSON Schema](http://json-schema.org/)for reference).

### Schema rules

[](#schema-rules)

1. there are two types of nodes:
    - `category`
    - `link`
2. there are four types of node fields (apart from `type` field which determines node type):
    - `title`
    - `url`
    - `description`
    - `children`
3. there is only one root `category` node
4. `category` nodes below root node REQUIRE valid `title` and may optionally contain other fields
5. `category` node CAN have child `category` nodes OR `link` nodes - but not both mixed at the same time
6. `link` node REQUIRE valid `title` and valid `url`, CAN have child `link` nodes and CANNOT have child `category` nodes

Examples
--------

[](#examples)

Here are some examples how Markdown fragments are parsed by Marklink parser into JSON data (see `tests/` directory for more).

### Basic example

[](#basic-example)

Input:

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

Output:

```
{
    "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)"
        }
    ]
}
```

### Advanced example

[](#advanced-example)

Input:

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

Output:

```
{
    "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",
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
```

### Input with markers

[](#input-with-markers)

By default Marklink parser will parse whole document unless it finds following markers:

```

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

```

In that case only content between markers will be parsed.

Online Marklink parsing service
-------------------------------

[](#online-marklink-parsing-service)

Initial Markling parser implementation is available as a service.

### Web interface

[](#web-interface)

### cURL example

[](#curl-example)

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

[](#php-example)

```
composer require kminek/marklink
```

```
use Kminek\Marklink\ParserService;

$markdown =