You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
148 lines
4.5 KiB
148 lines
4.5 KiB
# 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](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 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).
|
|
|