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