Static Marks

• Share your bookmarks app via a single self-contained HTML file.
• Use with any modern browser.
• Import bookmarks from Chrome, Firefox or Pocket.
• It's free and open source.

Demo

Features

• Use custom browser search engines with a ?search=%s URL param (example).
• Use custom web page templates. If you don't like the default UI, provide your own (example based on this template).
• Dark mode.

Quickstart

• Install Static Marks:

npm install -g static-marks

• Create a plain text bookmarks.yml YAML file containing your bookmarks. Alternatively, import your existing browser bookmarks:

static-marks import browser-bookmarks.html > bookmarks.yml

• Build your bookmarks app:

static-marks build bookmarks.yml > bookmarks.html

• Open bookmarks.html in your browser.

Installation

This tool requires Node.js version 12+.

• As a globally available CLI tool:

npm install -g static-marks

• As a local dependency in your project:

npm install --save static-marks

• Without installing:

npx static-marks <command>

• As a docker container (unofficial).

Usage

static-marks [options] <command>

Options:
  -V, --version               output the version number
  -h, --help                  output usage information

Commands:
  build [options] <files...>  build bookmarks app
  import [options] <file>     import bookmarks from chrome, firefox or pocket
  report <files...>           display bookmarks report

Run static-marks <command> --help to view the usage of a specific command.

Build bookmarks app

static-marks build [options] <files...>

Options:
  -o, --output [file]     output to a file (use stdout by default)
  -t, --title [title]     set document title
  --template-file [file]  use a custom web page template

Examples:

static-marks build bookmarks.yml > bookmarks.html  # Single file
static-marks build -o bookmarks.html bookmark.yml  # Alt. notation
static-marks build f1.yml f2.yml > bookmarks.html  # Multiple files
static-marks build files/* > bookmarks.html        # All files at path

Import bookmarks

static-marks import [options] <file>

Options:
  -o, --output [file]  output to a file (use stdout by default)

Examples:

static-marks import exported.html > imported.yml

View a report for your bookmarks

The report command displays the number of all bookmarks and lists any duplicates. In the future, it might be used for detecting dead links. too.

static-marks report [options] <files...>

Examples:

static-marks report bookmarks.yml
static-marks report files/*

File format

Bookmark files are written in YAML. There are multiple levels of hierarchy:

Collection:
  - Bucket:
      - Link: https://example.com

A link URL can be expressed either as an item property or as a child item:

- Link 1: https://example.com
- Link 2:
    - https://example.com

Notes and nested links are added as children of a link (the first element is the link URL). If the text is a valid-formatted URL, it will be automatically converted to a link:

- Link with notes:
    - https://example.com
    - This is a text note
    - Link note: https://example.com
    - https://example.net

First-level notes can be used to describe or structure a bucket:

- Bucket:
    - Link 1: https://example.com
    - Carpe diem!

Here's a complete example:

Collection:
  - Bucket:
      - Link 1: https://example.com
      - Link 2:
          - https://example.com
      - Link with notes:
          - https://example.com
          - This is a text note
          - Link note: https://example.com
      - First-level note

There is an optional 1st level hierarchy level available when you provide more than one bookmark file to static-marks. When passing multiple files, a header menu will be displayed to toggle between individual files and all bookmarks.

# file toggle menu not necessary/not available
$ static-marks build file1.yaml

# file toggle menu available
$ static-marks build file1.yaml file2.yaml

Using Static Marks with Gitlab Pages

You can leverage GitLab Pages to host your Static Marks instance. Check out the example repository and a live demo.

1. Create a new GitLab repository.
2. Include the example .gitlab-ci.yml file in the root directory.
3. Add all your bookmark *.yml files in a bookmarks directory.

After every push to the main branch, your Static Marks page will be rebuilt. By default, it will be available at https://<USERNAME>.gitlab.io/<PROJECTNAME>.

Development and Contribution

The frontend part of Static Mark is maintained in a separate repository, where a template file (_template.html) is being generated. This approach makes it possible to include the whole application and user-defined bookmarks in a single HTML file.

If you want to provide any frontend-related changes, please create a PR in the other repository. Changes to the core CLI application are handled here instead.

License

This project and its contents are open source under the MIT license.