Garrett Mills

Standard MarkMark (v1.0)

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.

Example:

<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) designed to render properly in vanilla Markdown clients.

MARKMARK := FRONTMATTER \n LINES

LINES :=
    LINE LINES
    | LINE EOF
    | EOF

LINE := SECTION | LINK

Frontmatter

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


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

Sections

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

# Technical Blogs

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

LINK :=
    - STRING TAGS\nINDENT HREFS

TAGS :=
    TAG TAGS
    | EOF

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.

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

- 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


[//]: # (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 by Garrett Mills is marked with CC0 1.0 Universal.