{"id":14964397,"url":"https://github.com/antistic/plover_markdown_dictionary","last_synced_at":"2025-10-25T07:30:46.503Z","repository":{"id":57453602,"uuid":"381541063","full_name":"antistic/plover_markdown_dictionary","owner":"antistic","description":"Plover plugin to support markdown dictionaries","archived":false,"fork":false,"pushed_at":"2022-03-15T11:57:28.000Z","size":37,"stargazers_count":3,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-09-30T02:32:29.973Z","etag":null,"topics":["markdown","plover"],"latest_commit_sha":null,"homepage":"","language":"Python","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/antistic.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}},"created_at":"2021-06-30T01:28:33.000Z","updated_at":"2024-07-26T06:29:11.000Z","dependencies_parsed_at":"2022-08-29T11:11:32.390Z","dependency_job_id":null,"html_url":"https://github.com/antistic/plover_markdown_dictionary","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/antistic%2Fplover_markdown_dictionary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistic%2Fplover_markdown_dictionary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistic%2Fplover_markdown_dictionary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistic%2Fplover_markdown_dictionary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antistic","download_url":"https://codeload.github.com/antistic/plover_markdown_dictionary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219866311,"owners_count":16555905,"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":["markdown","plover"],"created_at":"2024-09-24T13:33:07.581Z","updated_at":"2025-10-25T07:30:41.225Z","avatar_url":"https://github.com/antistic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plover Markdown Dictionary\n\nThis is a markdown file with embedded code blocks, in the style of literate programming. Each code block contains a YAML-like bit of text defining your entries.\n\nThis project was borne out of a desire for a dictionary format with these features:\n\n- easy to read and write by hand\n- simple for non programmers\n- allows comments\n- editable (add/update/delete) through the Plover interface, without losing comments\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [Git version](#git-version)\n  - [Status](#status)\n  - [For development](#for-development)\n- [Format](#format)\n  - [Where to put your definitions](#where-to-put-your-definitions)\n  - [Definition Format](#definition-format)\n  - [Comments](#comments)\n  - [Repeat definitions](#repeat-definitions)\n- [GUI Behaviour](#gui-behaviour)\n  - [Adding](#adding)\n  - [Deleting](#deleting)\n  - [Updating](#updating)\n- [Converting to/from other formats](#converting-tofrom-other-formats)\n- [Example](#example)\n- [Notes](#notes)\n  - [Alternative dictionary formats](#alternative-dictionary-formats)\n  - [Performance](#performance)\n  - [Why use `(UPDATED)` or `(DELETED)` tags?](#why-use-updated-or-deleted-tags)\n  - [Why this definition format?](#why-this-definition-format)\n  - [Contributing](#contributing)\n\n## Installation\n\nInstall via the Plover plugin manager.\n\n### Git version\n\nOn the [command-line](https://plover.readthedocs.io/en/latest/cli_reference.html) (requires git):\n\n```bash\nplover -s plover_plugins install git+https://github.com/antistic/plover_markdown_dictionary.git\n```\n\n### Status\n\nThis plugin is experimental and might have some bugs. Feel free to [open an issue](./issues/new) if you find one, and read the changelog when upgrading.\n\n### For development\n\n```bash\ngit clone https://github.com/antistic/plover_markdown_dictionary\ncd plover_markdown_dictionary\nplover -s plover_plugins install -e .\n```\n\n## Format\n\n- It's a Markdown file, so you can do all the [Markdown formatting](https://commonmark.org/help/) you like!\n\n### Where to put your definitions\n\n- Put your definitions in code blocks.\n\n```\nHRAOEUBG: like\nTH: this\n```\n\nwhich in markdown looks\n\n````md\n```\nHRAOEUBG: like\nTH: this\n```\n````\n\n- You can set the syntax formatting language to YAML\n\n\u003e **Note:** Although it looks like yaml, it isn't yaml.\n\n```yaml\nTH/STEUL: this still\nWORBGS: works\n```\n\nwhich in markdown looks like\n\n````md\n```yaml\nTH/STEUL: this still\nWORBGS: works\n```\n````\n\n- Code blocks defined as other formats will not be read as dictionary definitions. This makes it easy to comment out sections.\n\n```text\nKOPLT/-D: commented\nOUT: out\n```\n\nwhich looks like\n\n````md\n```text\nKOPLT/-D: commented\nOUT: out\n```\n````\n\n- `Inline` code blocks are will not be read as dictionary definitions.\n\n- Code blocks defined by indentation (e.g. 4 spaces) will not be read as dictionary definitions.\n\n### Definition Format\n\n- The basic format is `STROKES: translation`. Both the left and right side of the colon are treated as strings, even though they may not be in YAML.\n\n```yaml\n#S: 1\n2: 2\n-T: the\n*UR: you are\nKWRE: yes\n```\n\n- You can quote these if you wish to preserve syntax formatting\n\n```\n'#S': '1'          # single quotes\n'2': '2'\n\"-T\": the           # double quotes\n\"*UR\": you are\nKWRE: \"yes\"\n```\n\n- There are some characters you will need to escape:\n\n```yaml\nSKW-T: \\' # single quote character\nKR-GS: \\\" # double quote character\nHAERB: \\# # hash character on the right hand side\n'#-T': 9 # you should not escape the # in strokes\nPW-RB: \\\\ # backslash\nR-R: \\\\n # newline\nR*R: \\\\r # other newline\nTAB: \\\\t # tab\n```\n\n- But you might prefer to use quotes:\n\n```yaml\nSKW-T: \"'\"\nKR-GS: '\"'  # you can quote double quotes with single quotes\nHAERB: '#'\nPW-RB: \"\\\\\" # backslashes always need escaping, whether they're in quotes or not\nR-R: \"\\\\n\" # same with newlines\nR*R: \"\\\\r\"\nTAB: \"\\\\t\" # and tabs\nS-PS: ' ' # you'll need quotes for anything with starting or trailing spaces\n```\n\n### Comments\n\nYou can use comments after entries. These must be on the same line, and they're denoted by a `#` symbol.\n\n```yaml\nK-PLT: comment # this is a comment\n```\n\n### Repeat definitions\n\nYou should avoid specifying the same stroke(s) multiple times. If you choose to do this anyway, you should assign the same translation every time. The plugin will make a best effort to update all rows of the same chord when Plover updates or deletes entries.\n\n```yaml\nREPT: reptile  # this is overridden and ignored by Plover\nREPT: repeat\n```\n\n```yaml\nREPT: repeat\nREPT: repeat # it will only appear once in Plover, but we'll try to reflect changes everywhere\n```\n\n## GUI Behaviour\n\n\u003e **NOTE**: You shouldn't edit the file both in the Plover GUI and in your text editor at the same time, because it might lead to inconsistencies.\u003cbr\u003e\n\u003e If you have edited the file manually, you can reload it in Plover by unchecking and rechecking the box next to the dictionary, or reloading with `CTRL+R`.\n\n### Adding\n\nWhen you add an entry within the Plover interface, a section is created at the bottom of the file and entries are added. If the section already exists (defined by a heading with the text 'Added via Plover' then a single code block at the bottom of the file), it will add to that block.\n\nExample of what you'll see at the bottom of the file:\n\n````md\n## Added via Plover\n\n```yaml\nTPHU: new\nSPWREUS: entries\nTKPW: go\nHAOER: here\n```\n````\n\n### Deleting\n\nWhen you delete an entry, the line in the document is updated with a `(DELETED)` prefix and will be ignored when loading the dictionary in the future.\n\nExample of deleting `TKHRAOET/PHE: delete me`\n\n```yaml\nKP-PL: example\n(DELETED) TKHRAOET/PHE: delete me # this is ignored by Plover\nTEGT: text\n```\n\n### Updating\n\nWhen the translation is updated, the entry in the document is updated in place, and annotated with an `(UPDATED)` prefix for legibility; it is still read as normal by Plover.\n\nExample of changing `KP-L: example` to `KP-L: excel`\n\n```yaml\nKP-PL: example\n(UPDATED) KP-L: excel\nKPW-PL: example\n```\n\nWhen the stroke is updated it is treated like a deletion of the old entry then the addition of the new one.\n\n## Converting to/from other formats\n\n1. In the dictionaries list, select the dictionaries you want to convert.\n2. Right click, choose \"Save dictionaries as...\".\n3. Choose whether you want to create a copy of each dictionary, or merge into a new one.\n4. In the save file dialog, choose where to save the dictionary. To convert to JSON, save with the extension \".json\". To convert to Markdown, save with the extension \".md\".\n\n## Example\n\nThis file is an example! You can see the raw markdown [here](https://raw.githubusercontent.com/antistic/plover_markdown_dictionary/main/README.md).\n\nIt is equivalent to [example.json](./example.json).\n\n## Notes\n\nThis format is a work in progress and I'd love to get feedback on what works or doesn't work for you!\n\n### Alternative dictionary formats\n\nThere are other plover dictionary formats that allow comments, but all of them have something that means they don't fit my original goals (as of June 2021).\n\n| format                                                     | comments                                                                                                                                                            |\n| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Excel](https://pypi.org/project/plover-excel-dictionary/) | Dropped support for keeping comments on changing translations (in the form of other columns) in version 1.0.0                                                       |\n| [yaml](https://pypi.org/project/plover-yaml-dictionary/)   | Does not support keeping comments, citing performance reasons. Yaml also has weird catches with strings, like needing \"no\" in quotes (otherwise parsed as boolean). |\n| rtf/cre ([built-in support][rtf-1], [better-rtf][rtf-2])   | The format is hard to read (personal opinion)                                                                                                                       |\n| [hjson](https://pypi.org/project/plover-hjson-dictionary/) | Does not support keeping comments on dictionary updates                                                                                                             |\n\n[rtf-1]: https://github.com/openstenoproject/plover/wiki/Supported-formats#rtf-aka-cre\n\n[rtf-2]: https://pypi.org/project/plover-better-rtf/\n\n### Performance\n\nBasic tests with the plover main dictionary using [time.py](.scripts/time.py) on my laptop.\n\nI haven't tried very hard to optimise this, so it's probably possible to go faster.\n\n| Test                          | Time  |\n| ----------------------------- | ----- |\n| Load JSON                     | 0.44s |\n| Load JSON + Save JSON         | 1.15s |\n| Load JSON + Save Markdown     | 1.52s |\n| Load Markdown                 | 1.48s |\n| Load Markdown + Save Markdown | 2.36s |\n\n### Why use `(UPDATED)` or `(DELETED)` tags?\n\nIt's important that people know what's been changed so that they can make sure any description or comment stays up to date.\n\nThis could have been done via a version control system like git, but git requires a learning curve that non-programmers might not be comfortable with. Since people are likely to have to update the surrounding comments anyway, I thought it would not be too much work to remove the tags.\n\nFor those who are comfortable, you can always clone this repository, alter `DELETED_PREFIX` and `UPDATED_PREFIX` in [./plover\\_markdown\\_dictionary.py](./plover_markdown_dictionary.py), and install your local version with `plover -s plover_plugins install -e .`.\n\n### Why this definition format?\n\njson does not support comments. hjson (\u0026 other json extensions) and yaml are are not performant enough to be viable (according to the people making the dictionary plugins. I haven't tried).\n\nThis particular format was chosen to be easy to read and write. It looks very similar to the default json, but does not require quotes nor commas. One downside is that it's not easy to copy and paste between this format and the default json, but I haven't decided how important that is for the format yet.\n\nI've also gone for an unstructured format for metadata (comments and Markdown) since other formats (e.g. JSON) are probably better structured metadata.\n\n### Contributing\n\nIf you have any questions or problems, feel free to open an issue! I'll also gladly take suggestions in the form of pull requests as well.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantistic%2Fplover_markdown_dictionary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantistic%2Fplover_markdown_dictionary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantistic%2Fplover_markdown_dictionary/lists"}