{"id":15578823,"url":"https://github.com/witoso/hammernotion","last_synced_at":"2025-03-29T07:43:54.424Z","repository":{"id":205615079,"uuid":"443979690","full_name":"Witoso/hammernotion","owner":"Witoso","description":"Hammerspoon automation for Notion","archived":false,"fork":false,"pushed_at":"2022-12-29T17:30:36.000Z","size":49,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-03T21:39:57.320Z","etag":null,"topics":["hammerspoon","notion","notion-api"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Witoso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-01-03T07:46:36.000Z","updated_at":"2023-10-28T09:01:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"c76b3327-61de-4bc2-87cc-a56ac08527ff","html_url":"https://github.com/Witoso/hammernotion","commit_stats":null,"previous_names":["witoso/hammernotion"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Witoso%2Fhammernotion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Witoso%2Fhammernotion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Witoso%2Fhammernotion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Witoso%2Fhammernotion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Witoso","download_url":"https://codeload.github.com/Witoso/hammernotion/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246156029,"owners_count":20732359,"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":["hammerspoon","notion","notion-api"],"created_at":"2024-10-02T19:13:02.114Z","updated_at":"2025-03-29T07:43:54.404Z","avatar_url":"https://github.com/Witoso.png","language":"Lua","readme":"# HammerNotion\n\nA plugin for automating page creation in Notion via [Hammerspoon](https://www.hammerspoon.org/).\n\nWorks only on MacOS.\n\n## Why?\n\nI often find myself with a need of recording something with as little context switching as possible. For example, I'm on a call, listening to my stakeholder, and I want to quickly record a task for myself without changing the apps. I use Notion as a task db, so I needed something that works with it.\n\nWith HammerNotion, I use a keyboard shortcut \u003ckbd\u003eCMD\u003c/kbd\u003e + \u003ckbd\u003eCTRL\u003c/kbd\u003e + \u003ckbd\u003eQ\u003c/kbd\u003e, write `todo this is an important task!` in the opened modal, and a page gets created in Notion.\n\n## Installation\n\n**It's not an official Spoon yet.** I plan to add it when I finish some of the todos, therefor installation and configuration might take some additional steps.\n\n1. Install Hammerspoon.\n2. Create a 'Spoons' dir in your `.hammerspoon` dir.\n3. Create a `HammerNotion.spoon` dir in `Spoons`.\n4. Download and copy `init.lua` to `HammerNotion.spoon` dir.\n5. (Optional) Download and install [Seal](https://www.hammerspoon.org/Spoons/Seal.html) spoon to get launch bar capabilities.\n\n## Configuration\n\n1. Create your integration in Notion https://www.notion.so/my-integrations and get your secret token. Remember to add create permissions.\n2. Connect this integration to the database page you wish to automate.\n3. Create two files in your `.hammerspoon` dir: `notion-config.json` and `notion-secret.json`\n\n`notion-secret.json` keeps your API secret and should look like this:\n\n```json\n{\n  \"api_key\": \"YOUR_SECRET\"\n}\n```\n\n`notion-config.json` stores your HammerNotion config.\n\n```json\n{\n  \"NAME_OF_DB\": {\n    \"type\": \"database_id\",\n    \"database_id\": \"YOUR_DATABASE_ID\",\n    \"properties\": {\n      \"first\": {\n        \"key\": \"Name\",\n        \"type\": \"title\"\n      },\n      \"s\": {\n        \"key\": \"Status\",\n        \"type\": \"select\"\n      },\n      \"u\": {\n        \"key\": \"Url\",\n        \"type\": \"url\"\n      }\n    }\n  }\n}\n```\n\n- NAME_OF_DB - name you will use to in the code.\n- type - keep it as is.\n- database_id - id of our database.\n- properties - hash with your properties. It has the key used in your query (`first` is an exception), `key` expected by Notion API (name of the field), and `type` (property type in Notion). Right now HammerNotion supports 3 properties: title, select, url.\n\nExamples in the usage section.\n\n## Usage and Examples\n\n_Remember that this only works when you are online as Notion API is used to save new pages._\n\nThe scanarios below use Seal spoon.\n\n### Simple scenario\n\nCreate a config file.\n\n```json\n{\n  \"todo\": {\n    \"type\": \"database_id\",\n    \"database_id\": \"YOUR_DATABASE_ID\",\n    \"properties\": {\n      \"first\": {\n        \"key\": \"Name\",\n        \"type\": \"title\"\n      },\n      \"s\": {\n        \"key\": \"Status\",\n        \"type\": \"select\"\n      }\n    }\n  }\n}\n```\n\nIn your `.hammerspoon/init.lua` prepare the code for automation.\n\n```lua\nhs.loadSpoon(\"Seal\")\nhs.loadSpoon(\"HammerNotion\")\n\nhn = spoon.HammerNotion\nhn:loadConfig(true) -- this loads config, true flag start debug mode, additional info is printed to the console.\n\nspoon.Seal:loadPlugins({ \"useractions\" })\nspoon.Seal:bindHotkeys({\n\ttoggle = { { \"cmd\", \"ctrl\" }, \"Q\" }, -- map keys from Seal.\n})\n\nspoon.Seal.plugins.useractions.actions = {\n\t[\"Todo\"] = {\n\t\tkeyword = \"todo\",\n\t\tfn = function(query)\n\t\t\tlocal query = query .. \"|s:Todo\" -- manually add the status to query.\n\t\t\tlocal properties = hn:getProperties(query, \"|\", \":\", \"todo\") -- get the table with properties prepared for notion.\n\t\t\thn:createPage(\"todo\", properties) -- create a page in todo database.\n\t\tend,\n\t},\n}\nspoon.Seal:start()\n\n```\n\nAfter hitting the key combination, the Seal launcher will open, and you need to type `todo {your page title}` + \u003ckbd\u003eENTER\u003c/kbd\u003e, and the page will be created in status Todo.\n\n### Advanced scenario\n\nHammernotion let's you write queries that will setup multiple fields on your page, you need to set up properties in the config file as well as seperators for query.\n\n```json\n{\n  \"talkwith\": {\n    \"type\": \"database_id\",\n    \"database_id\": \"YOUR_DATABASE_ID\",\n    \"properties\": {\n      \"first\": {\n        \"key\": \"Name\",\n        \"type\": \"title\"\n      },\n      \"w\": {\n        \"key\": \"With\",\n        \"type\": \"select\"\n      }\n    }\n  }\n}\n```\n\nIn your `.hammerspoon/init.lua` prepare the code for automation.\n\n```lua\nhs.loadSpoon(\"Seal\")\nhs.loadSpoon(\"HammerNotion\")\n\nhn = spoon.HammerNotion\nhn:loadConfig(true) -- this loads config, true flag start debug mode, additional info is printed to the console.\n\nspoon.Seal:loadPlugins({ \"useractions\" })\nspoon.Seal:bindHotkeys({\n\ttoggle = { { \"cmd\", \"ctrl\" }, \"Q\" }, -- map keys from Seal.\n})\n\nspoon.Seal.plugins.useractions.actions = {\n\t[\"Talk With\"] = {\n\t\tkeyword = \"talk\",\n\t\tfn = function(query)\n\t\t\tlocal properties = hn:getProperties(query, \"|\", \":\", \"talkwith\") -- | seperator defines how fields are split, : defines key value seperator.\n\t\t\thn:createPage(\"talkwith\", properties) -- create a page in todo database.\n\t\tend,\n\t},\n}\nspoon.Seal:start()\n\n```\n\nAfter hitting the key combination, the Seal launcher will open, and you can type `talk {your page title} | w:Adam` + \u003ckbd\u003eENTER\u003c/kbd\u003e, and the page will be created with property `With` with value `Adam`.\n\n## Todo\n\n- [ ] Add more Notion API properties\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwitoso%2Fhammernotion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwitoso%2Fhammernotion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwitoso%2Fhammernotion/lists"}