{"id":15650014,"url":"https://github.com/bachya/pinpress","last_synced_at":"2025-04-15T01:06:50.745Z","repository":{"id":15998995,"uuid":"18742281","full_name":"bachya/pinpress","owner":"bachya","description":"A simple CLI to create text templates of Pinboard data.","archived":false,"fork":false,"pushed_at":"2021-12-02T21:02:09.000Z","size":145,"stargazers_count":38,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T13:02:56.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bachya.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-13T23:08:30.000Z","updated_at":"2025-03-03T12:53:13.000Z","dependencies_parsed_at":"2022-08-30T14:01:54.050Z","dependency_job_id":null,"html_url":"https://github.com/bachya/pinpress","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Fpinpress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Fpinpress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Fpinpress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bachya%2Fpinpress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bachya","download_url":"https://codeload.github.com/bachya/pinpress/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248714750,"owners_count":21149961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T12:33:01.452Z","updated_at":"2025-04-15T01:06:50.720Z","avatar_url":"https://github.com/bachya.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"PinPress\n========\n[![Build Status](https://travis-ci.org/bachya/pinpress.svg?branch=master)](https://travis-ci.org/bachya/pinpress)\n[![Gem Version](https://badge.fury.io/rb/pinpress.svg)](http://badge.fury.io/rb/pinpress)\n\nPinPress is a simple CLI to create templates (HTML, Markdown, or otherwise) of\nPinboard pins and tags.\n\n# Why?\n\nEvery week, I create a [link mash for my blog](#link-mash-config-file); this\nlink mash consists of URLs that I find interesting and want to share with my\nreaders. Previously, I would save those interesting URLs to an Evernote note\nand, every week, manually create my link mash for use in Wordpress. `\u003cbarf/\u003e`\n\nWhen I began using [Pinboard](http://pinboard.in \"Pinboard\") to save\ninteresting links, I knew I needed a better method. This tool is the result:\n**Pin** board + Word **press**.\n\n# Prerequisites\n\nIn addition to Git (which, given you being on this site, I'll assume you have),\nRuby (v. 1.9.3 or greater) is needed.\n\n# Installation\n\n```bash\ngem install pinpress\n```\n\n# Usage\n\nSyntax and usage can be accessed by running `pinpress help`:\n\n```bash\n$ pinpress help\nNAME\n    pinpress - A Pinboard application that allows for the creation of\n    \"pin templates\" in almost any conceivable format.\n\nSYNOPSIS\n    pinpress [global options] command [command options] [arguments...]\n\nVERSION\n    1.6.3\n\nGLOBAL OPTIONS\n    --help    - Show this message\n    --version - Display the program version\n\nCOMMANDS\n    help      - Shows a list of commands or help for one command\n    init      - Install and initialize dependencies\n    pins      - Get posts from Pinboard\n    tags      - Get tags from Pinboard\n    templates - Work with templates for pin output\n```\n\nNote that each command's options can be revealed by adding the `--help` switch\nafter the command. For example:\n\n```bash\n$ pinpress pins --help\nNAME\n    pins - Get posts from Pinboard\n\nSYNOPSIS\n    pinpress [global options] pins [command options]\n\nCOMMAND OPTIONS\n    -a     - Auto-links any URLs found in a pin description\n    -c     - Copy final output to the system clipboard\n    -e arg - The end date to pull pins to (default: none)\n    l      - Allows the user to create \u003ca\u003e links around detected URLs\n    -m arg - The pin template to use (default: none)\n    -n arg - The number of results to return (default: none)\n    -s arg - The start date to pull pins from (default: none)\n    -t arg - The tags to use (e.g., \"ruby,pinboard\") (default: none)\n\nCOMMANDS\n    \u003cdefault\u003e -\n    last      - Gets all pins from the last run date + 1\n```\n\n# Initialization\n\n```bash\n$ pinpress init\n```\n\nInitialization will prompt you to enter your Pinboard API token. Once, entered,\nthis (and other pertinent data) will be stored in `~/.pinpress`.\n\n# Getting Pins\n\n```bash\n$ pinpress pins\n```\n\nThis simple command will return all pins from the user's account and output them\nbased on the [Pin Template](#pin-templates \"Pin Templates\") provided.\n\nPinpress also provides some flags that allow a user to define specific pins to\ngrab:\n\n* `-s`: the start date to use (uses [Chronic](https://github.com/mojombo/chronic \"Chronic\"), which allows dates like \"last Tuesday\")\n* `-e`: the end date to use (also uses [Chronic](https://github.com/mojombo/chronic \"Chronic\"))\n* `-m`: the PinPress template to use\n* `-n`: the number of pins to return (e.g., 20)\n* `-t`: a CSV list of tags (e.g., \"tag1,tag2\") that must exist for the returned pins\n\n## Output\n\nBy default, pin template text will be output to the terminal; you can use the\n`-c` switch to output it to the system clipboard instead. This flag makes use\nof the [clippy](https://github.com/envygeeks/clippy) gem, which\nallows for cross-platform system clipboard access. Make sure you read its\n[README](https://github.com/envygeeks/clippy/blob/master/Readme.md).\n\n## Getting Pins From a Date Forward\n\n```bash\n$ pinpress pins -s 2014-01-01\n```\n\n...returns all pins from January 1, 2014 to the current day.\n\n## Getting Pins Until a Date\n\n```bash\n$ pinpress pins -e 2014-01-01\n```\n\n...returns all pins up to January 1, 2014.\n\n## Getting Pins Between a Date Range\n\n```bash\n$ pinpress pins -s 2014-01-01 -e 2014-01-31\n```\n\n## Getting Tagged Pins\n\n```bash\n$ pinpress pins -t \"ruby,cli\"\n```\n\n...returns all pins tagged \"ruby\" *and* \"cli\".\n\n**Naturally, these flags can be combined in any number of ways.**\n\n## Getting Pins Created Since Last Run\n\n```bash\n$ pinpress pins last\n```\n\n...will get all the pins created since you last ran that command (e.g., if you'd\nlast run `pinpress pins` on 2014-01-01, this command would return all pins\ncreated from 2014-01-02 onward).\n\n# Getting Tags\n\nPinpress can also work with tags in a Pinboard account:\n\n```bash\n$ pinpress tags\n```\n\nThis simple command will return all tags from the user's account and output them\nbased on the [Tag Template](#tag-templates \"Tag Templates\") provided.\n\nPinpress also provides some flags that allow a user to define specific tags to\ngrab:\n\n* `-m`: the PinPress template to use\n* `-s`: the start date to use (uses [Chronic](https://github.com/mojombo/chronic \"Chronic\"), which allows dates like \"last Tuesday\")\n* `-e`: the end date to use (also uses [Chronic](https://github.com/mojombo/chronic \"Chronic\"))\n\n## Output\n\nBy default, pin template text will be output to the terminal; you can use the\n`-c` switch to output it to the system clipboard instead. This flag makes use\nof the [clippy](https://github.com/envygeeks/clippy) gem, which\nallows for cross-platform system clipboard access. Make sure you read its\n[README](https://github.com/envygeeks/clippy/blob/master/Readme.md).\n\n## Getting Tags From a Date Forward\n\n```bash\n$ pinpress tags -s 2014-01-01\n```\n\n...returns all tags used from January 1, 2014 to the current day. Note that for\neach tag returned, the data includes both the tag name and the number of times\nit was used.\n\n## Getting Tags Until a Date\n\n```bash\n$ pinpress tags -e 2014-01-01\n```\n\n...returns all tags used up to January 1, 2014.\n\n## Getting Tags Between a Date Range\n\n```bash\n$ pinpress tags -s 2014-01-01 -e 2014-01-31\n```\n\n## Getting Tags Used Since Last Run\n\n```bash\n$ pinpress tags last\n```\n\n...will get all the tags used since you last ran the command (e.g., if you'd\nlast run `pinpress tags` on 2014-01-01, this command would return all tags used\nfrom 2014-01-02 onward).\n\n# Templates\n\nTemplates are used to define how data should be output to the terminal and are\ndefined in `~/.pinpress`. They come in two forms: **Pin Templates** and **Tag\nTemplates**.\n\n## Pin Templates\n\nPin Templates define how a pin from Pinboard should be output.\n\n### Schema\n\nPin Templates are placed under the `pin_templates` section of the `~/.pinpress`\nconfig file -- as an example:\n\n```yaml\npin_templates:\n- pinpress_default:\n    opener: \"\u003cul\u003e\\n\"\n    item: \u003e\n      \u003cli\u003e\n      \u003cb\u003e\u003ca title=\"\u003c%= description %\u003e\" href=\"\u003c%= href %\u003e\" target=\"_blank\"\u003e\n      \u003c%= description %\u003e\u003c/a\u003e.\u003c/b\u003e\n      \u003c%= extended %\u003e\n      \u003c/li\u003e\n    closer: \"\u003c/ul\u003e\"\n# ... other templates ...\n```\n\nA Pin Template can have several different sub-keys:\n\n* `opener` (*optional*): the text that should exist above the pins\n* `closer` (*optional*): the text that should exist below the pins\n* `item` (**required**): the formatted text that should be output for every pin\n\n### Available Tokens\n\nAdditionally, a Pin Template can make use of several different tokens that are\nfilled by a pin's values:\n\n* `\u003c%= href %\u003e`: the URL of the pin\n* `\u003c%= description %\u003e`: the description of the pin\n* `\u003c%= extended %\u003e`: the pin's longer assocated description\n* `\u003c%= tag %\u003e`: the CSV list of tags that apply to the pin\n* `\u003c%= time %\u003e`: the time the pin was added to Pinboard\n* `\u003c%= replace %\u003e`: the replacement status of the pin\n* `\u003c%= shared %\u003e`: the privacy status of the pin\n* `\u003c%= toread %\u003e`: the \"to-read\" status of the pin\n\n### Usage\n\nPin Templates can be used in two ways: they can either be called dynamically:\n\n```bash\n$ pinpress pins -m template_name\n```\n\n...or a default template can be specified in `~/.pinpress`:\n\n```yaml\n---\npinpress:\n  config_location: \"/Users/abach/.pinpress\"\n  default_pin_template: pinpress_default\n  # ... other keys ...\npin_templates:\n- pinpress_default:\n    opener: \"\u003cul\u003e\\n\"\n    item: \u003e\n      \u003cli\u003e\n      \u003cb\u003e\u003ca title=\"\u003c%= description %\u003e\" href=\"\u003c%= href %\u003e\" target=\"_blank\"\u003e\n      \u003c%= description %\u003e\u003c/a\u003e.\u003c/b\u003e\n      \u003c%= extended %\u003e\n      \u003c/li\u003e\n    closer: \"\u003c/ul\u003e\"\n# ... other templates ...\n```\n\nSo, knowing the above, both:\n\n```bash\n$ pinpress pins\n```\n\n...and:\n\n```bash\n$ pinpress pins -m pinpress_default\n```\n\n...will output pin data in the format specified by that template:\n\n```html\n\u003cul\u003e\n  \u003cli\u003e\n    \u003cb\u003e\n      \u003ca href=\"http://www.macstories.net/tutorials/launch-center-pro-guide/\"\u003e\n        Automating iOS: A Comprehensive Guide to Launch Center Pro\n      \u003c/a\u003e.\n    \u003c/b\u003e\n    This the most amazing article I've seen in a long time. So many tips, tricks,\n    and automations to make productivity easier.\n  \u003c/li\u003e\n  \u003c!-- ... --\u003e\n\u003c/ul\u003e\n```\n\n(Note that the nice indenting is for Github's sake; the actual output will\nconform to the formatting in `~/.pinpress`.)\n\n## Tag Templates\n\nTag Templates are exactly like Pin Templates, but are used for tags.\n\n### Schema\n\nThey, too, are defined in `~/.pinpress`:\n\n```yaml\ntag_templates:\n- pinpress_default:\n    item: \"\u003c%= tag %\u003e (\u003c%= count %\u003e),\"\n```\n\nA Tag Template makes use of the same sub-keys as Pin Template:\n\n* `opener` (*optional*): the text that should exist above the tag string\n* `closer` (*optional*): the text that should exist below the tag string\n* `item` (**required**): the formatted text that should be output for every tag\n\n### Available Tokens\n\nAdditionally, like a Pin Template, a Tag Template can make use of a few tokens:\n\n* `\u003c%= tag %\u003e`: the name of the tag\n* `\u003c%= count %\u003e`: the number of times the tag has been used (depending on the\nrange used)\n\n### Usage\n\nPin Templates can be used in two ways: they can either be called dynamically:\n\n```bash\n$ pinpress tags -m template_name\n```\n\n...or a default template can be specified in `~/.pinpress`:\n\n```yaml\n---\npinpress:\n  config_location: \"/Users/abach/.pinpress\"\n  default_tag_template: pinpress_default\n  # ... other keys ...\npin_templates:\n  # ... other keys ...\ntag_templates:\n  # ... other keys ...\n# ... other templates ...\n```\n\nSo, knowing the above, both:\n\n```bash\n$ pinpress tags\n```\n\n...and:\n\n```bash\n$ pinpress tags -m pinpress_default\n```\n\n...will output tag data in the format specified by that template:\n\n```bash\nlink-mash (15),app (2),ios (3),productivity (1),launch-center-pro (1),drafts (2),\n```\n\n# URL Linking\n\nI often run into the situation where I want to take a URL from a pin's description\nand add an `\u003ca\u003e` tag around it (since Pinboard doesn't allow you to embed the HTML\nwithin the pin description itself). PinPress provides two mechanisms to accomplish\nthis: automatic linking and manual linking.\n\n## Automatic URL Linking\n\n### Using It\n\nTo use automatic linking, simply use the `-a` switch when running PinPress.\n\nAlternatively, to always use automatic linking, include a `auto_link` key/value\nin `~/.pinpress`:\n\n```yaml\npinpress:\n  auto_link: true\n```\n\nNote that the `auto_link` configuration key can be overridden by using a different\nURL linking switch (such as `-l`).\n\n### How It Works\n\nUsing this method, PinPress will scan each pin that is being requested for URLs.\nUpon finding a URL, PinPress will automatically wrap it in an `\u003ca\u003e` tag.\n\nFor example, given a description that looks like this:\n\n```html\n...this is some text with a URL: http://www.google.com.\n```\n\n...PinPress will modify the description such that the following is output\ninstead:\n\n```html\n...this is some text with a URL: \u003ca href=\"http://www.google.com\" target=\"_blank\"\u003ehttp://www.google.com\u003c/a\u003e.\n```\n\nFinally, this link gets stored in `~/.pinpress`:\n\n```yaml\nlinks:\n  # This ID is a combination of the URL\n  # and the pin in which it is found.\n  853d65b7e76a57955040e97902fc2b3c:\n    title: Pin with Google\n    url: http://www.google.com\n    link_text: http://www.google.com\n```\n\nThis happens for two reasons:\n\n1. Going forward, any request that returns this pin will use the data found\nin `~/.pinpress` (so that it doesn't have to be recalculated).\n2. If you want to modify the text that gets used for this link in this pin,\nyou can do it here.\n\n## Manual URL Linking\n\n### Using It\n\nTo use automatic linking, simply use the `-l` switch when running PinPress.\n\nAlternatively, to always use automatic linking, include a `manual_link` key/value\nin `~/.pinpress`:\n\n```yaml\npinpress:\n  manual_link: true\n```\n\nNote that the `manual_link` configuration key can be overridden by using a different\nURL linking switch (such as `-a`).\n\n### How It Works\n\nThis method is similar to automatic linking in that it will search each pin in the\noutput for URLs in its description. When found, the user is prompted to enter the\ntext that will create the link.\n\nFor example, given a description that looks like this:\n\n```html\nCheck out https://gifyoutube.com/!\n```\n\n...imagine that the user types in `GIF Youtube`; the result will look like this:\n\n```html\nCheck out \u003ca href=\"https://gifyoutube.com/\" target=\"_blank\"\u003eGIF Youtube\u003c/a\u003e!\n```\n\nLike automatic linking, the results of this URL/pin combo are stored in\n`~/.pinpress` for easy lookup and future editing.\n\n# Other Configuration Options\n\n## Global Keys\n\nYou can place special keys in the `pinpress` section of `~/.pinpress` to\nautomate some actions:\n\n```yaml\npinpress:\n  # ...other keys...\n\n  # The default pins template to use\n  default_pin_template: template_name\n\n  # The default tags template to use\n  default_tag_template: template_name\n\n  # Automatic URL linking; note that this\n  # cannot exist eat the same time as manual\n  # URL linking\n  auto_link: true\n\n  # Manual URL linking; note that this\n  # cannot exist eat the same time as auto\n  # URL linking\n  manual_link: true\n\n  # ...other keys...\n```\n\n## Template Keys\n\nIndividual templates can carry some special keys, too:\n\n```yaml\npin_templates:\n- template_name:\n    # ...other keys...\n\n    # The default tags to be used when running `pinpress pins`\n    default_tags: ['tag1', 'tag2']\n\n    # The tags to that are removed from the results when running `pinpress tags`\n    ignored_tags: ['bad-tag', 'bad-tag2']\n\n    # The default number of results to return\n    default_num_results: 5\n\n    # ...other keys...\n```\n\nDo note:\n\n* The `default_tags` key is overridden by the `-t` flag.\n* The `default_num_results` key is overridden by the `-n` flag.\n\n# Link Mash Config File\n\nFor your reference, here's my `~/.pinpress` (which is used to generate a\n[Link Mash on my blog](http://www.bachyaproductions.com/tag/link-mash/ \"Bachya Productions Link Mash Archives\")):\n\n```yaml\n---\npinpress:\n  config_location: \"/Users/abach/.pinpress\"\n  default_pin_template: pinpress_default\n  default_tag_template: pinpress_default\n  log_level: WARN\n  version: 1.6.0\n  api_token: bachya:1234567890987654321\n  manual_link: true\npin_templates:\n- pinpress_default:\n    opener: |\n      \u003cem\u003eThe weekly Link Mash is a curated selection of tools, stories, and other links that I found during my travels on the web. All of my links can be found on \u003ca title=\"Bachya's Pinboard: Link Mash\" href=\"https://pinboard.in/u:bachya/t:link-mash/\" target=\"_blank\"\u003emy Pinboard\u003c/a\u003e; you can also find the Link Mash archives \u003ca href=\"http://www.bachyaproductions.com/tag/link-mash/\"\u003ehere\u003c/a\u003e.\u003c/em\u003e\u003cul\u003e\n    item: |\n      \u003cli\u003e\u003cb\u003e\u003ca title=\"\u003c%= description %\u003e\" href=\"\u003c%= href %\u003e\" target=\"_blank\"\u003e\u003c%= description %\u003e\u003c/a\u003e.\u003c/b\u003e \u003c%= extended %\u003e\u003c/li\u003e\n    closer: |\n      \u003c/ul\u003e\u003chr/\u003e\u003cem\u003eThis Link Mash was generated by \u003ca title=\"PinPress\" href=\"https://github.com/bachya/pinpress\" target=\"_blank\"\u003ePinPress\u003c/a\u003e, a simple tool to generate text templates from \u003ca title=\"Pinboard\" href=\"https://pinboard.in\" target=\"_blank\"\u003ePinboard\u003c/a\u003e data.\u003c/em\u003e\n    last_run: '2014-05-20T15:22:10Z'\n    default_tags:\n    - link-mash\n    ignored_tags:\n    - buffer\ntag_templates:\n- pinpress_default:\n    item: \"\u003c%= tag %\u003e,\"\n    last_run: '2014-05-20T15:22:10Z'\n```\n\n# Known Issues \u0026 Future Releases\n\nCheck out the Pinpress roadmap via the\n[Trello Board](https://trello.com/b/lmuC8TT0/pinpress \"Pinpress Trello Board\").\n\nBugs, issues, and enhancement requests can be submitted on the\n[Issues Page](https://github.com/bachya/Pinpress/issues \"Open Items\").\n\n# Bugs and Feature Requests\n\nTo report bugs with or suggest features/changes for PinPress, please use the\n[Issues Page](http://github.com/bachya/PinPress/issues).\n\nContributions are welcome and encouraged. To contribute:\n\n* [Fork PinPress](http://github.com/bachya/PinPress/fork).\n* Create a branch for your contribution (`git checkout -b new-feature`).\n* Commit your changes (`git commit -am 'Added this new feature'`).\n* Push to the branch (`git push origin new-feature`).\n* Create a new [Pull Request](http://github.com/bachya/PinPress/compare/).\n\n# License\n\n(The MIT License)\n\nCopyright © 2014 Aaron Bach \u003cbachya1208@gmail.com\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the 'Software'), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\nthe Software, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbachya%2Fpinpress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbachya%2Fpinpress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbachya%2Fpinpress/lists"}