Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/darekkay/static-marks

Shareable bookmarks
https://github.com/darekkay/static-marks

bookmarks

Last synced: about 1 month ago
JSON representation

Shareable bookmarks

Host: GitHub
URL: https://github.com/darekkay/static-marks
Owner: darekkay
License: mit
Created: 2018-03-27T15:12:37.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2024-05-23T16:35:36.000Z (7 months ago)
Last Synced: 2024-10-11T04:46:26.525Z (2 months ago)
Topics: bookmarks
Language: HTML
Homepage: https://darekkay.com/static-marks
Size: 1.86 MB
Stars: 422
Watchers: 11
Forks: 31
Open Issues: 8
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

project-awesome - darekkay/static-marks - Shareable bookmarks (HTML)
jimsghstars - darekkay/static-marks - Shareable bookmarks (HTML)

README

# Static Marks

[![Build](https://img.shields.io/github/actions/workflow/status/darekkay/static-marks/ci.yml?branch=master&style=flat-square)](https://github.com/darekkay/static-marks/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/static-marks.svg?style=flat-square)](https://www.npmjs.com/package/static-marks)
[![license](https://img.shields.io/github/license/darekkay/static-marks.svg?style=flat-square)](https://github.com/darekkay/static-marks/blob/master/LICENSE)

Convert your **plain bookmark** files into a **static web app**.

![YAML to App diagram](assets/img/workflow.svg)

- **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](https://github.com/darekkay/static-marks).

🔖 [**View Live Demo**](https://darekkay.com/static-marks/demo/default.html)

## Demo

![Static Marks Screencast](assets/img/screencast.gif)

## Features

- Use custom browser search engines with a `?search=%s` URL param ([example](https://darekkay.com/static-marks/demo/default.html?search=fire)).
- 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](https://darekkay.com/static-marks/demo/custom.html) based on [this template](https://github.com/darekkay/static-marks/blob/master/docs/examples/templates/custom.html)).
- Dark Mode.

## Quickstart

- [Install](#installation) Static Marks:

```shell
npm install -g static-marks
```

- Create a plain text `bookmarks.yml` [YAML file](#file-format) containing your bookmarks. Alternatively, [import](#import-bookmarks) your existing browser bookmarks:

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

- [Build](#build-bookmarks-app) your bookmarks app:

```shell
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:

```bash
npm install -g static-marks
```

- As a local dependency in your project:

```bash
npm install --save static-marks
```

- Without installing:

```shell
npx static-marks
```

- As a [docker container](https://github.com/gaerfield/static-marks-docker) (unofficial).

## Usage

```
static-marks [options]

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

Commands:
build [options] build bookmarks app
import [options] import bookmarks from chrome, firefox or pocket
report report bookmarks
```

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

### Build bookmarks app

```
static-marks build [options]

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:

```bash
static-marks build -o bookmarks.html bookmark.yml # Single file
static-marks build bookmarks.yml > bookmarks.html # 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]

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

Examples:

```bash
static-marks import exported.html > imported.yml
static-marks import -o imported.yml exported.html
```

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

```bash
static-marks report [options]
```

Examples:

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

## File format

Bookmark files are written in [YAML](http://yaml.org). There are multiple levels of hierarchy:

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

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

```yaml
- 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:

```yaml
- 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:

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

Here's a complete example:

```yaml
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.

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

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

## Troubleshooting

### Encoding issues

You can use both `>` to pipe the results of a `static-marks` command or the `-o` to provide an explicit output file. There might be cases where the `>` variant doesn't play well with the shell encoding, though.

See [#46](https://github.com/darekkay/static-marks/issues/46) for more information.

## Using Static Marks with Gitlab Pages

You can leverage [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) to host your Static Marks instance. Check out the [example repository](https://gitlab.com/darekkay/static-marks-gitlab-ci) and a [live demo](https://darekkay.gitlab.io/static-marks-gitlab-ci).

1. [Create](https://gitlab.com/projects/new) a new GitLab repository.
2. Include the example [.gitlab-ci.yml](docs/examples/ci/.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://.gitlab.io/`.

## Development and Contribution

The frontend part of Static Mark is maintained in [another repository](https://github.com/darekkay/static-marks-app), 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.

## Contributors

Thanks goes to these wonderful people: