Skip to content

Latest commit

 

History

History
100 lines (68 loc) · 3.64 KB

ADVANCED-USAGE.md

File metadata and controls

100 lines (68 loc) · 3.64 KB
Raw

Advanced usage

The top level README shows the basic get functionality but there are more options and ways to use Bookworms.

Get

Create bookmarks from local or remote YMAL.

$ npx bookworms get ./my-bookmarks.yaml

This will then generate in the ./ directory the different exports you can then use in your older tools.

$ ls
browsers.html README.md

You can also fetch bookmarks from a remote location and output the exports into a directory:

$ npx bookworms get https://raw.githubusercontent.com/thearegee/bookworms/main/demo/config/bookmarks.yaml -d="./output"

Interpolating bookmarks

merge works well when you have multiple local or remote YAML that all sit at the top level however you might have a situation where they need to be at different levels in your folder structure. For this you can use the interpolation helper within your YAML file.

label: Interpolated bookmarks
description: This is an example of interpolating YAML files
folders:
  -
    {{ get './my-bookmarks.yaml' '    '}}
  -
    {{ get 'https://raw.githubusercontent.com/thearegee/bookworms/main/demo/config/bookmarks-for-merging.yaml' '    '}}

All YAML files are passed through Handlebars. There is a registered helper called get that takes two parameters.

  • path - load local or remote bookmarks from path
  • indentation - the amount of spaces or tabs needed to indent the block. You can copy and paste this from the first { to the starting line.

NOTE: I appreciate this indentation parameter is pretty gross at the time of writing this I couldn't think of a better way without potentially writing my own parser for the YAML file. If someone is interesting in conbributing and changing this code it would be welcome.

Merge

merge works in a similar way to get with the same options but it allows you to create bookmarks from multiple local or remote YAML.

$ npx bookworms merge ./my-bookmarks.yaml ./my-company-bookmarks.yaml https://raw.githubusercontent.com/thearegee/bookworms/main/demo/config/bookmarks.yaml

In this example Bookworms is merging together multiple bookmark YAML files, by default it will merge them into one top level folder called "Merged worms" but you can override the label and the description with the command:

$ npm start -- merge ./my-bookmarks.yaml ./my-company-bookmarks.yaml https://raw.githubusercontent.com/thearegee/bookworms/main/demo/config/bookmarks.yaml -l="My bookmarks" -t="Bookmarks my personal bookmarks, my bookmarks from work and remote bookmarks that interest me"

Convert

If you already have bookmarks in your browser you can speed up the process of converting them into YAML using the convert tool, read more about that here: Exporting existing bookmarks.

The convert command works in a similar way to get with the same options.

$ npx convert ./browsers.html -d="./output"
$ ls
converted-bookmarks.yaml

You can also override the default filname.

$ npx convert ./browsers.html -f="./my-bookmarks.yaml"
$ ls
my-bookmarks.yaml

Check

Check whether current generated files are up to date with the yaml file. This can be used either in a git hook or in your CI to make sure the output files have been changed after a change to the yaml file.

The check command works in a similar way to get with the same options.

$ npx bookworms check ./my-bookmarks.yaml

This will print whether the generated bookmark files are up to date. The process will also exit with exit code 0 if the files are up to date, and 1 if not.