Markdown Bookmark (md-bookmark)

• Introduction
• API

Introduction

This specification defines a simple standard for saving and sharing bookmarks as Markdown files with front matter metadata.

The goal is an offline-first approach to bookmarking, allowing bookmarks to be stored as individual Markdown files that can be synced across devices using any standard cloud syncing service (e.g., Dropbox, Google Drive).

By using file over app, this approach ensures user data is not locked into proprietary systems, offering freedom to migrate bookmarks between apps or platforms easily.

Front Matter Fields

| Field | Type | Description | Required | | ------------- | ------ | -------------------------------------------- | -------- | | title | String | The title of the bookmark. | Yes | | url | String | The url of the bookmarked page or resource. | Yes | | type | String | The type of resource. | Yes | | cover_image | String | A cover image representing the bookmark. | No | | tags | List | An optional list of tags or keywords. | No | | created_at | Date | The date the bookmark was created. | No | | updated_at | Date | The last modified date of the bookmark file. | No |

Content Section

The content section of the Markdown file is optional and can include any relevant notes, summaries, or additional information about the bookmark. This section can contain:

• Freeform text
• Markdown elements such as links, images, code snippets, bullet points, etc.
• Annotations or personal comments related to the bookmarked content

File Naming Convention

The naming convention of bookmark files plays a crucial role in the usability and organization of bookmarks. We propose some key strategies for naming Markdown bookmark files.

1. Kebab Case Based on Title

Each bookmark file should be named using kebab-case (lowercase letters with hyphens between words) derived from the bookmark title, with special characters stripped out. This ensures that file names are human-readable, predictable, and avoid issues with file systems that may not support certain characters.

This approach makes the file easily identifiable by its name while remaining compatible across different operating systems.

2. Optional Use of Unique IDs

There is an option to use unique identifiers (e.g., timestamps, UUIDs) to file names to ensure uniqueness across bookmarks. This can be useful when dealing with bookmarks that have identical or similar titles. However, this approach has a key drawback: the resulting file names may be less intuitive for users, as they would no longer directly represent the content.

3. File Name Should Reflect Bookmark Content

The file name should reflect the content or purpose of the bookmark as closely as possible. This is important for both human readability and effective organization. Users should be able to tell, at a glance, what a bookmark file contains without needing to open it.

Use the webpage or resource title where possible.

4. Handling Duplicate Bookmark Titles

In scenarios where the same bookmark is saved multiple times, or different bookmarks share the same title, we may detect duplicates while still allowing variations. This can be done by checking the URL field and other metadata to identify whether a bookmark with the same content already exists, even if the titles are identical.

To handle this, bookmarks with duplicate titles can either:

• Add a numeric suffix to the file name (e.g., markdown-bookmark-file-specification-1.md, markdown-bookmark-file-specification-2.md).
• Include the date or other disambiguating information in the file name to distinguish them.

This approach avoids overwriting files with identical names while keeping the file name informative and easily understandable.

5. Date Prepend for Chronological Organization

For users who prefer to organize bookmarks chronologically, an option could be provided to prepend the date to the file name. This would help users quickly identify when a bookmark was saved, even without opening the file.

This strategy is especially useful for users managing large numbers of bookmarks, allowing for easier sorting and retrieval by date.

6. Namespace for Collections

If users categorize their bookmarks into collections (e.g., folders or topics), it might be helpful to use namespaces in file names. For example, prefixing the file name with the collection name:

reading-markdown-bookmark-file-specification.md
tools-markdown-bookmark-file-specification.md

This would further enhance file organization and discovery by visually grouping related bookmarks in file systems.

API

The bookmark model

title string

The title of the bookmark.

url string

The URL of the bookmarked page or resource.

type string

The type of the resource (e.g., article, video).

cover_image string

A URL for a cover image representing the bookmark.

tags string[]

An optional list of tags or keywords associated with the bookmark.'

created_at Date (Readonly)

The date the bookmark was created.

updated_at Date (Readonly)

The last modified date of the bookmark, which is updated whenever the bookmark is saved.

save() function

A method that saves the bookmark as a Markdown file to the specified filePath.

toObject() function

A method that converts the bookmark object into a plain JavaScript object.

toMarkdown() function

A method that converts the bookmark object to a Markdown string with front matter metadata.

createBookmark

Create a bookmark to be saved as Markdown file with front matter metadata.

[!NOTE] It does not validate urls and empty strings.

import { createBookmark } from "@chewhx/md-bookmark";

Parameters

filePath string (Required)

createBookmarkParams object (Required)

• title string (Required)
• url string (Required)
• type string (Required)
• cover_image string
• tags string[]

Returns

The bookmark model

loadBookmark

Load a bookmark from markdown file.

• It will not overwrite additional front matter fields, not found in the bookmark model.
• It will throw if the following fields are absent: title, url, cover_image, type.

[!NOTE] It does not validate urls and empty strings.

import { loadBookmark } from "@chewhx/md-bookmark";

Parameters

filePath string (Required)

Returns

The bookmark model