Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
January 17, 2023 11:37
April 5, 2022 21:39
August 2, 2020 19:12
August 2, 2020 19:27
October 13, 2020 22:03
March 19, 2021 19:57
April 5, 2022 21:39
May 12, 2021 23:05
January 17, 2023 11:37
April 5, 2022 21:39
April 5, 2022 21:38

Static Marks

Build npm license

Convert your plain bookmark files into a static web app.

YAML to App diagram

  • 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.

🔖 View Live Demo


Static Marks Screencast


  • Use custom browser search engines with a ?search=%s URL param (example).
    • In Firefox, right-click the Static Marks search field and select "Add a Keyword for this Search".
  • Use custom web page templates. If you don't like the default UI, provide your own (example based on this template).
  • Dark Mode.


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.


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>


static-marks [options] <command>

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

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

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

Build bookmarks app

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

  -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


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>

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


static-marks import exported.html > imported.yml

View a report for your bookmarks

Currently, the report contains only the total bookmarks count. In the future, it might be used for detecting duplicate and dead links.

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


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

File format

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

  - Bucket:
      - Link:

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

- Link 1:
- Link 2:

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:
    - This is a text note
    - Link note:

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

- Bucket:
    - Link 1:
    - Carpe diem!

Here's a complete example:

  - Bucket:
      - Link 1:
      - Link 2:
      - Link with notes:
          - This is a text note
          - Link note:
      - 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 master branch, your Static Marks page will be rebuilt. By default, it will be available at https://<USERNAME><PROJECTNAME>.

Development and Contribution

The frontend part of Static Mark is maintained in another 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.


Thanks goes to these wonderful people:

darekkay gaerfield kaushalyap k-kalinowski g33k247 dzmitry-lahoda diegombeltran veerreshr nausher acer123acer123
jflip e-minguez iaeiou Jiehong RishiKumarRay overflowy

This project follows the all-contributors specification to acknowledge all contributions.


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