---
layout: markmark
permalink: /markmark/standard/
---

**MarkMark is an extremely simple, standard, plain-text format for collecting bookmarks in such a way that they can be shared and federated.**

## File Format & Rel-Links

MarkMark files SHOULD be stored as plain-text Markdown files with the extension `.mark.md`.

Example: `john-doe.mark.md`

You MAY refer to a MarkMark file in the `<head>` tag of an HTML document as you would with, for example, and RSS feed using the media type `text/markdown;variant=markmark`.  This media type is derived from [RFC 7763](https://www.rfc-editor.org/rfc/rfc7763).

Example:
```html
<link rel="alternate" href="/john-doe.mark.md" title="My Bookmarks" type="text/markdown;variant=markmark"/>
```

## Syntax

MarkMark is a subset of Markdown (specifically [CommonMark](https://spec.commonmark.org/)) designed to render properly in vanilla Markdown clients.

```text
MARKMARK := FRONTMATTER \n LINES

LINES :=
    LINE LINES
    | LINE EOF
    | EOF

LINE := SECTION | LINK
```

### Frontmatter

```txt
FRONTMATTER := \n [//]: # (FRONTMATTER_VALUE)

FRONTMATTER_VALUE :=
    markmark-syntax: v1
    | markmark-author-name: STRING
    | markmark-author-email: STRING
    | markmark-author-href: STRING
```

MarkMark uses a subset of Markdown Link Reference Definitions (CommonMark §4.7) to add MarkMark-specific metadata to the file. These values MUST appear at the top of the file. These values SHOULD be provided. The first FrontMatter item MUST be prefixed with a newline character (`\n`). You MAY prefix subsequent FrontMatter items with a newline character (`\n`). You MUST suffix the last FrontMatter item with a newline character (`\n`).

#### Supported Properties

- `markmark-syntax` - The MarkMark spec version (supported values: `v1`)
- `markmark-author-name` - The name of the author of this bookmark collection
- `markmark-author-email` - The email address of the author
- `markmark-author-href` - The URL of the author's website

#### Example

```markdown

[//]: # (markmark-syntax: v1)
[//]: # (markmark-author-name: John Doe)
[//]: # (markmark-author-email: john.doe@example.com)
[//]: # (markmark-author-href: https://john-doe.example.com/)
```

### Sections

```text
SECTION := # STRING
    | # STRING \n STRING
```

In MarkMark, authors MAY organize their bookmarks into sections. These sections MUST be indicated using a Markdown Heading 1 syntax (CommonMark §4.2) and MAY be followed by a Markdown Paragraph (CommonMark §4.8) describing the section.

#### Example

```markdown
# Technical Blogs

This is a description of the Technical Blogs section in my MarkMark file.
```

### Links

```text
LINK :=
    - STRING DATE TAGS\nINDENT HREFS

DATE := (ISO8601) | EOL

TAGS :=
    TAG TAGS
    | EOL

TAG := #SLUG

INDENT := ␣␣␣␣ | \t

HREFS :=
    - URL
    | - [URL](URL)
```

Links are individual entries in a bookmark collection and represent a bookmark title and one or more URLs relevant to that bookmark. These URLs SHOULD be limited to less than 5.

A link is a Markdown Bullet List item (CommonMark §5.2) with a sub-list of URLs. Each URL MUST be either a plain-text URL OR a Markdown Link (CommonMark §6.3). Markdown Link URLs MUST use the URL as the only text for the link.

#### Dates (v1.1)

Each link MAY have one date associated with it. The date associated with a link SHOULD refer to the date the link was accessed by the author and added to the collection. The date MAY refer to the publication date of the associated media.

Dates MUST be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates) format and MUST minimally include the year, month, and day.

#### Tags

Each link MAY have one or more tags associated with it. Tags provide an additional organizational scheme as they can be used to associate links across sections.

Tags are composed of a `#`-sign followed by a slug composed of alpha-numeric-underscore-dash `a-zA-Z0-9_\-` characters. Multiple tags MUST be separated by one or more space characters.

If a link has tags, those tags MUST appear at the end of the line containing the link's title, after one or more space characters.

#### Example

```markdown
- My Blog  #personal-site #blog
    - https://john-doe.example.com/blog
- Jane's Blog  #blogs
    - https://jane-doe.example.com/blog
- Example.com
    - [https://example.com](https://example.com)
```

## Full Example

```markdown

[//]: # (markmark-syntax: v1)
[//]: # (markmark-author-name: John Doe)
[//]: # (markmark-author-email: john.doe@example.com)
[//]: # (markmark-author-href: https://john-doe.example.com/)

# Doe-Family Sites

Here is a collection of personal blogs and homepages from members of the Doe family.

- My Blog  #personal-site #blog
    - https://john-doe.example.com/blog
- Jane's Blog  #blogs
    - https://jane-doe.example.com/blog
- Example.com
    - [https://example.com](https://example.com)
```

## License

[Standard MarkMark](https://garrettmills.dev/markmark) by [Garrett Mills](https://garrettmills.dev/) is marked with [CC0 1.0 Universal](http://creativecommons.org/publicdomain/zero/1.0?ref=chooser-v1).


## Change Log

- `v1.1`: Added spec for optional dates
- `v1.0`: Initial Standard
