{"id":13397728,"url":"https://github.com/waldobronchart/ShortcutMapper","last_synced_at":"2025-03-14T00:32:40.249Z","repository":{"id":16859393,"uuid":"19619480","full_name":"waldobronchart/ShortcutMapper","owner":"waldobronchart","description":"A visual keyboard shortcuts explorer for popular applications.","archived":false,"fork":false,"pushed_at":"2023-06-27T00:52:03.000Z","size":5258,"stargazers_count":794,"open_issues_count":11,"forks_count":145,"subscribers_count":50,"default_branch":"master","last_synced_at":"2024-07-31T18:21:22.281Z","etag":null,"topics":["keyboard","keyboard-layout","keyboard-shortcut","keyboard-shortcuts","shortcut-key","shortcut-layout","shortcutkey","shortcuts","shortcuts-layout"],"latest_commit_sha":null,"homepage":"http://waldobronchart.github.io/ShortcutMapper/","language":"HTML","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/waldobronchart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-05-09T17:29:33.000Z","updated_at":"2024-07-29T03:31:07.000Z","dependencies_parsed_at":"2024-01-15T13:33:40.187Z","dependency_job_id":null,"html_url":"https://github.com/waldobronchart/ShortcutMapper","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waldobronchart%2FShortcutMapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waldobronchart%2FShortcutMapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waldobronchart%2FShortcutMapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waldobronchart%2FShortcutMapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waldobronchart","download_url":"https://codeload.github.com/waldobronchart/ShortcutMapper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243504976,"owners_count":20301537,"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":["keyboard","keyboard-layout","keyboard-shortcut","keyboard-shortcuts","shortcut-key","shortcut-layout","shortcutkey","shortcuts","shortcuts-layout"],"created_at":"2024-07-30T18:01:41.725Z","updated_at":"2025-03-14T00:32:37.464Z","avatar_url":"https://github.com/waldobronchart.png","language":"HTML","readme":"ShortcutMapper\n==================\n\nThis is a keyboard shortcuts visualiser hosted here on Github:\nhttp://waldobronchart.github.io/ShortcutMapper/\n\nThe goal of this project is to map out application keyboard shortcuts onto a virtual keyboard, making it easy to find and learn new shortcuts. The shortcut data is scraped from online documentation to reduce error and to keep the data easy to update with newer versions.\n\n![Imgur](http://waldobronchart.github.io/ShortcutMapper/content/images/overview.gif)\n\n# Overview\n\nThis project is directly hosted on github from the **master** branch. All changes to this branch are live.\n\n```\n/content         The website content\n    /generated   Contains generated json/js files containing application\n                  shortcut data in the site format\n    /keyboards   Contains html keyboard layouts\n    ...\n/sources         Source data for shortcuts per application.\n/shmaplib        Python utility library (Shortcut Mapper Lib) to help \n                  exporting shortcuts to the webapp.\n/tests           Python tests to ensure nothing is broken\n/utils           Utilities for exporting and testing\nindex.html       Main site page\n```\n\n# Contributing\n\n## Running locally\n\nBefore opening pull requests to contribute, you should test your changes locally.\n\nThe easiest way to run locally is to run a simple http server:\n1. Install http-server via npm: `npm install -g http-server`\n2. Run `http-server` in your terminal\n  \u003e Starting up http-server, serving ./\n  \u003e Available on:\n  \u003e   http://127.0.0.1:8080\n  \u003e   http://192.168.86.95:8080\n  \u003e Hit CTRL-C to stop the server\n3. Go to http://127.0.0.1:8080 in your browser\n\n## Exporting new updated shortcuts\n\nThe exporter scripts all use Python3 and some additional libraries. I recommend you use [virtualenv](http://virtualenv.readthedocs.org/en/latest/) like so:\n\n```\n# Install pip if you don't have it yet\nsudo easy_install pip\n\n# Install virtualenv\npip install virtualenv\n\n# Create a virtual environment in ShortcutMapper/_venv directory\n# For Windows, look here for instructions: \n# http://virtualenv.readthedocs.io/en/latest/userguide/#usage\ncd ShortcutMapper/\nvirtualenv -p /usr/bin/python3 _venv\n\n# Activate environment\nsource _venv/bin/activate\npip install BeautifulSoup4\n\n# Do an export\npython exporters/adobe-photoshop/scripts/export.py -a\n```\n\nOnce your virtualenv in installed, all you need to do is activate it before you run the exporters\n\n```\nsource _venv/bin/activate\n\n# For windows, you will do this instead\n_venv\\Source\\activate.bat\n\n# Export all intermediate json files to content/generated/\npython utils/export_intermediate_data.py -a\n```\n\n\n## Adding shortcuts for a new Application\n\n**The best example you can look at is Autodesk Maya under /sources/autodesk-maya**\n\n### Exporters directory setup\n\nFirst, try and find an online resource that lists all the application shortcuts for each platform. For adobe applications for example, I use the ones from their online documentation: http://helpx.adobe.com/lightroom/help/keyboard-shortcuts.html\n\nMake sure it's up-to-date and the list is complete.\n\nYou're going to use that resource to create an intermediate data format that can be edited by hand easily.\n\nCreate a directory structure under **/sources** like this:\n```\n/sources\n    /my-app\n        /intermediate           One-time conversions from raw data, which have been hand edited to\n                                 fix faulty shortcuts and shorten labels that are too long.\n        /raw                    Source(s) used to build a full shortcut list in the intermediate data format\n```\n\nThen ideally, you're going to write a script that converts the raw source to intermediate: `/sources/my-app/raw_to_intermediate.py`\n\nPast the intermediate data creation step, everything can be automated. Much of the heavy lifting code lives under the `shmaplib` folder.\n\n### Using SHMAPlib\n\nSHMAPlib is short for \"Shortcut Mapper Lib\". It's a Python library that will help you export data in the right format to the right location.\n\nIf your script lives and runs directly in **/sources/app/**, then you can import the lib like so:\n\n```\n# Add repository root path to sys.path (This will make import shmaplib work)\nCWD = os.path.dirname(os.path.abspath(__file__))\nsys.path.insert(0, CWD)\nsys.path.insert(0, os.path.normpath(os.path.join(CWD, '..', '..')))\n\n# Import common shortcut mapper library\nimport shmaplib\n```\n\nFrom there you can parse your raw files (HTML, XML, etc..) and create an intermediate data file which can then be hand edited.\n\n```\nimport shmaplib\n\n# Create the intermediate data container\nidata = shmaplib.IntermediateShortcutData(\"Application Name\")\n\n# Parse the raw file\n# ...and add shortcuts to the container like this:\ncontext_name = \"Global Context\"\nlabel = \"Select All\"\nkeys_win = \"Ctrl + A\"\nkeys_mac = \"Cmd + A\"\nidata.add_shortcut(context_name, label, keys_win, keys_mac)\n\n# Save out the file\nidata.serialize('intermediate/my-application_v3.json')\n```\n\nYou can then export this intermediate data file after making hand-edits (there are always edge cases to fix).\n\n```\n# Export intermediate to the frontend data format\npython utils/export_intermediate_data.py sources/application-name/intermediate/SOURCE.json\n```\n\nIf your application doesn't have an intermediate format (like Blender), you can use these structures to build up the data:\n- *shmaplib.ApplicationConfig*: Main application data format (name, os, version, and shortcut-contexts)\n- *shmaplib.ShortcutContext*: A container for shortcuts for a specific context (Lightroom: Global, Develop, Library)\n- *shmaplib.Shortcut*: Data format for a shortcut (name, key and modifiers)\n\nYou'll create an AppConfig first. Then create a new context to the application, to which the shortcuts are added\n\nAppConfig has multiple ShortcutContexts, which has multiple Shortcuts.\n\nThe AppConfig has a serialize function that exports it into the correct directory under /content/generated\n\nLook in `shmaplib/appdata.py` for more specific docs.\n\n\n## Pull Requests Flow\n\nI follow the git-flow process to get new features and bugfixes in. You can read about it here:\nhttps://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow\n\nBasically you'll create a branch like `feature/descriptive-feature-name` from the `master` branch and start working in that. Once you're done, you'll create a pull request that merges into the `dev` branch.\nThis allows me to test your changes before it is published to the `master` branch.\n\nFor bug fixes, you'll name your branch `fix/descriptive-bug-name`.\n\n### Expected contents for new keyboards\n\nIdeally both windows and mac keyboards, created from other existing layouts (Klingon for example):\n- content/keyboards/klingon.html\n- content/keyboards/klingon_mac.html\n\nThese files added to the keyboard list in `content/keyboards/keyboards.js`\n```\nvar sitedata_keyboards = {\n    ...\n    \"Klingon\": {\n        mac: \"klingon_mac.html\",\n        windows: \"klingon.html\",\n        linux: \"klingon.html\",\n    }\n}\n```\n\nMake sure to run all tests in the `/tests` folder to ensure all keycodes are valid.\n\n### Expected contents for new applications\n\nPlease make sure to read the \"Adding shortcuts for a new Application\" section above.\nIt is good practice to keep your commits small and structured so it's easy to review.\n\nFirst I find a raw source and write a scraper script to generate the intermediate file (Example: https://github.com/waldobronchart/ShortcutMapper/commit/76f7b2f6c895bebebd5a5948c3bc759ac7779189)\n-  sources/thefoundry-nuke/raw/nuke_8.0_user_guide_hotkeys.html\n-  sources/thefoundry-nuke/raw_to_intermediate_nuke8.py\n\nGenerate the intermediate file with the `raw_to_intermediate` script (Example: https://github.com/waldobronchart/ShortcutMapper/commit/f1db1aa3268e0a82b5394d7e1c26335153872cb5)\n- sources/thefoundry-nuke/intermediate/thefoundry_nuke_8.0.json\n\nMake some needed hand edits to the intermediate files, like better grouping in contexts and fixing some long names. It's good to have the original untouched one in first, so that you can track your changes more easily (Example: https://github.com/waldobronchart/ShortcutMapper/commit/767556431a983481abd7cc0a30f1878cceef5fe9)\n- sources/thefoundry-nuke/intermediate/thefoundry_nuke_8.0.json\n\nKeep re-generating the app content (with `/utils/export_intermediate_data`) until you're happy with the changes. Note to fix the warnings during the export process.\n\nWhen you're happy with all the changes, commit the generated data (Example: https://github.com/waldobronchart/ShortcutMapper/commit/5533cdf94e9cab5564b9a946f528638cea6420f3)\n- content/generated/apps.js (app was added here)\n- content/generated/the-foundry-nuke_8.0_mac.json\n- content/generated/the-foundry-nuke_8.0_windows.json\n\nThen create a new pull request into the `develop` branch.\n","funding_links":[],"categories":["HTML"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaldobronchart%2FShortcutMapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaldobronchart%2FShortcutMapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaldobronchart%2FShortcutMapper/lists"}