{"id":15704172,"url":"https://github.com/alexkrolick/search-notes","last_synced_at":"2025-09-13T01:09:24.505Z","repository":{"id":68377779,"uuid":"291934558","full_name":"alexkrolick/search-notes","owner":"alexkrolick","description":"A search index and more for your markdown notes","archived":false,"fork":false,"pushed_at":"2020-09-14T02:20:24.000Z","size":118,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-06T17:58:30.761Z","etag":null,"topics":["frontmatter","index","lunr","markdown","search","tagging"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/alexkrolick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-09-01T07:58:44.000Z","updated_at":"2025-04-26T11:56:31.000Z","dependencies_parsed_at":"2023-05-04T08:47:51.607Z","dependency_job_id":null,"html_url":"https://github.com/alexkrolick/search-notes","commit_stats":{"total_commits":15,"total_committers":2,"mean_commits":7.5,"dds":0.2666666666666667,"last_synced_commit":"119c4e89024c9d4a788b960fa6b54f185fa8068a"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fsearch-notes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fsearch-notes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fsearch-notes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexkrolick%2Fsearch-notes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexkrolick","download_url":"https://codeload.github.com/alexkrolick/search-notes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252741371,"owners_count":21797027,"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":["frontmatter","index","lunr","markdown","search","tagging"],"created_at":"2024-10-03T20:10:36.299Z","updated_at":"2025-05-12T16:41:33.509Z","avatar_url":"https://github.com/alexkrolick.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# search-notes\n\nA search index and more for your markdown notes.\n\n```sh\nsearch-notes highlands              basic text search\nsearch-notes name:wallace           search yaml frontmatter\nsearch-notes \"tag:royalty britain\"  multiple terms\nsearch-notes \"brit*\"                prefix search\nsearch-notes \"scatlond~1\"           fuzzy search\nsearch-notes \"tags:stuart -france\"  exclude terms\nsearch-notes \"tags:stuart +france\"  boolean AND\nsearch-notes \"britain^2 france^1\"   boost terms\n```\n\n```\n% search-notes \"scot* +tags:stuart\" -d ./test/notes\nSearch took 0.017599736 seconds\n┌─────────┬─────────────────────┬─────────┬────────────────────────────────────────────┐\n│ (index) │        File         │  Score  │                    Hits                    │\n├─────────┼─────────────────────┼─────────┼────────────────────────────────────────────┤\n│    0    │ 'prince-charlie.md' │ '0.221' │ '\"scotland\" (body, tags), \"stuart\" (tags)' │\n│    1    │   'queen-anne.md'   │ '0.189' │    '\"scotland\" (body), \"stuart\" (tags)'    │\n└─────────┴─────────────────────┴─────────┴────────────────────────────────────────────┘\n```\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [search-notes](#search-notes)\n  - [Install](#install)\n  - [Features](#features)\n    - [Metadata search](#metadata-search)\n    - [Tag search](#tag-search)\n    - [Link search](#link-search)\n    - [Graphing Relations](#graphing-relations)\n  - [CLI](#cli)\n    - [Caching the search index](#caching-the-search-index)\n      - [Without Cache](#without-cache)\n      - [With Cache](#with-cache)\n      - [Using the --write-cache (-w) flag](#using-the---write-cache--w-flag)\n  - [TODO](#todo)\n  - [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Install\n\nZero-install: use npx to download and run\n\n```\nnpx search-notes query\n```\n\nGlobal:\n\n```\nnpm install -g local-notes\nsearch-notes query\n```\n\n## Features\n\n### Metadata search\n\nParses YML frontmatter into structured data you can query.\n\n```md\n---\ntitle: Scottish History\nyear: 2020\n---\n\n# Scottish History\n\nThis is the body of the post.\nYou can query it using fuzzy search.\n```\n\n```\nsearch-notes \"title:scottish year:202* past~1\"\n```\n\n### Tag search\n\n```md\nHashtags are #indexed so you can #query them\n```\n\n```sh\nsearch-notes tags:something\n```\n\n### Link search\n\nOutgoing links are indexed, so you can look up \"backlinks\" (incoming links) by searching what links to a file. You can look up any link this way, not just local documents. E.g., you can find all documents that link to Wikipedia.\n\n```md\n# Find all documents that link to a page\n\nsearch-notes -d test/notes \"linksTo:SomePage\"\n```\n\n```md\n# See all links\n\nsearch-notes -d test/notes \"linksTo:\\*\"\n```\n\n### Graphing Relations\n\nThe `--graph` (`-g`) option produces a [Mermaid](https://github.com/mermaid-js/mermaid) diagram of the entity relationships in your files. Right now this is tags and links.\n\n```\nsearch-notes --graph\n```\n\n```mermaid\nflowchart LR;\n\n\t'james-stuart.md'([\"James Francis Edward Stuart\"]) --\u003e 'pretender.md'\n\ttags_pretender[#pretender] -.- 'james-stuart.md'([\"James Francis Edward Stuart\"])\n\n\ttags_pretender[#pretender] -.- 'pretender.md'([\"pretender.md\"])\n\n\t'prince-charlie.md'([\"Bonnie Prince Charlie\"]) --\u003e 'james-stuart.md'\n\t'prince-charlie.md'([\"Bonnie Prince Charlie\"]) --\u003e 'pretender.md'\n\ttags_stuart[#stuart] -.- 'prince-charlie.md'([\"Bonnie Prince Charlie\"])\n\ttags_royal[#royal] -.- 'prince-charlie.md'([\"Bonnie Prince Charlie\"])\n\ttags_scotland[#scotland] -.- 'prince-charlie.md'([\"Bonnie Prince Charlie\"])\n\ttags_france[#france] -.- 'prince-charlie.md'([\"Bonnie Prince Charlie\"])\n\ttags_monarch[#monarch] -.- 'prince-charlie.md'([\"Bonnie Prince Charlie\"])\n\ttags_highlands[#highlands] -.- 'prince-charlie.md'([\"Bonnie Prince Charlie\"])\n\ttags_pretender[#pretender] -.- 'prince-charlie.md'([\"Bonnie Prince Charlie\"])\n\n\ttags_stuart[#stuart] -.- 'queen-anne.md'([\"Queen Anne\"])\n\ttags_royal[#royal] -.- 'queen-anne.md'([\"Queen Anne\"])\n\ttags_britain[#britain] -.- 'queen-anne.md'([\"Queen Anne\"])\n\n\nsubgraph Tags\n\t\ttags_pretender[#pretender]\n\t\ttags_pretender[#pretender]\n\t\ttags_stuart[#stuart]\n\t\ttags_royal[#royal]\n\t\ttags_scotland[#scotland]\n\t\ttags_france[#france]\n\t\ttags_monarch[#monarch]\n\t\ttags_highlands[#highlands]\n\t\ttags_pretender[#pretender]\n\t\ttags_stuart[#stuart]\n\t\ttags_royal[#royal]\n\t\ttags_britain[#britain]\nend\n```\n\nYou can turn the chart into an image or PDF using Mermaid's CLI.\n\nIf you have `@mermaid-js/mermaid-cli` installed globally:\n\n```\nsearch-notes --graph \u003e graph.mmd | mmdc -i graph.mmd -o graph.png\n```\n\nIf you have `npx`:\n\n```\nsearch-notes --graph \u003e graph.mmd | npx -p @mermaid-js/mermaid-cli mmdc -i graph.mmd -o graph.png\n```\n\n![graph](./test/notes/graph.png)\n\n## CLI\n\n```\nsearch-notes --help\n```\n\n```text\nsearch-notes [query]\n\nSearch for notes using structured data and full text index, with fuzzy matching.\n\nPositionals:\n  query  text to search for                                                                        [string] [default: \"\"]\n\nOptions:\n  --directory, -d    directory to search in                                                        [string] [default: \"\"]\n  --cache, -c        cached search index to use (ignored if file doesn't exist)         [string] [default: \"search.json\"]\n  --write-cache, -w  create or update search index cache file                                  [boolean] [default: false]\n  --explain          show relevance score and other details for results                         [boolean] [default: true]\n  --version          Show version number                                                                        [boolean]\n  --help             Show help                                                                                  [boolean]\n\nExamples:\n  search-notes highlands               basic text search\n  search-notes name:wallace            search yaml frontmatter\n  search-notes \"tags:royalty britain\"  multiple terms\n  search-notes \"brit*\"                 prefix search\n  search-notes \"scatlond~1\"            fuzzy search\n  search-notes \"scatlonz~2\"            fuzzier search\n  search-notes \"tags:stuart -france\"   negate term\n  search-notes \"tags:stuart +france\"   boolean AND\n  search-notes \"britain^2 france^1\"    boost term relevance\n  search-notes \"linksTo:filename\"      incoming links\n  search-notes --graph                 create node graph in mmd format\n  search-notes -w                      re-index folder and save cache to disk\n  search-notes -c index.json query     specify index cache file\n```\n\n### Caching the search index\n\nWriting the search index to disk will significantly speed up subsequent queries.\nThe downside is you need to remember to update it when you files change.\nIn the future there might be a filesystem watch mode that can do this for you.\n\nIf you want to stop using the cache, just delete the file.\n\n#### Without Cache\n\n```\n% search-notes \"scot* tags:stuart\" -d ./test/notes\nSearch took 0.018347418 seconds\n┌─────────┬──────────────────────┬─────────┬────────────────────────────────────────────┐\n│ (index) │         File         │  Score  │                    Hits                    │\n├─────────┼──────────────────────┼─────────┼────────────────────────────────────────────┤\n│    0    │ 'william-wallace.md' │ '1.181' │            '\"scottish\" (body)'             │\n│    1    │ 'prince-charlie.md'  │ '0.221' │ '\"scotland\" (body, tags), \"stuart\" (tags)' │\n│    2    │   'queen-anne.md'    │ '0.189' │    '\"scotland\" (body), \"stuart\" (tags)'    │\n└─────────┴──────────────────────┴─────────┴────────────────────────────────────────────┘\n```\n\n#### With Cache\n\n```\n% search-notes \"scot* tags:stuart\" -d ./test/notes\nSearch took 0.001248612 seconds\n┌─────────┬──────────────────────┬─────────┬────────────────────────────────────────────┐\n│ (index) │         File         │  Score  │                    Hits                    │\n├─────────┼──────────────────────┼─────────┼────────────────────────────────────────────┤\n│    0    │ 'william-wallace.md' │ '1.181' │            '\"scottish\" (body)'             │\n│    1    │ 'prince-charlie.md'  │ '0.221' │ '\"scotland\" (body, tags), \"stuart\" (tags)' │\n│    2    │   'queen-anne.md'    │ '0.189' │    '\"scotland\" (body), \"stuart\" (tags)'    │\n└─────────┴──────────────────────┴─────────┴────────────────────────────────────────────┘\n```\n\n#### Using the --write-cache (-w) flag\n\nYou can invoke `search-notes -w` with no search option to index the folder and write the index to disk.\n\n```\n% search-notes -d ./test/notes -w\nUpdated index file in 0.02012653 seconds\nSearch took 0.021347405 seconds\n┌─────────┬──────────────────────┬─────────┬──────┐\n│ (index) │         File         │  Score  │ Hits │\n├─────────┼──────────────────────┼─────────┼──────┤\n│    0    │ 'prince-charlie.md'  │ '0.000' │  ''  │\n│    1    │   'queen-anne.md'    │ '0.000' │  ''  │\n│    2    │ 'william-wallace.md' │ '0.000' │  ''  │\n└─────────┴──────────────────────┴─────────┴──────┘\n```\n\n## TODO\n\n- [x] index/reindex command\n- [x] search command\n- [x] index links between notes (`\"linksTo:somewhere.md linkedFrom:elsewhere.md\"`)\n- [x] backlink visualizer (node graph)\n  - [x] static output\n  - [x] use mermaid-cli\n  - [ ] web page output\n  - [ ] filter-then-display\n- [ ] index nested folders\n- [ ] add package version to the cache file to verify compatibility\n- [ ] more sensible search defaults (see elasticlunr)\n- [ ] more output formatting options\n  - [ ] add json output mode\n  - [ ] print snippet of file around hits (like `grep -n`)\n- [ ] add more remarkable plugins out of the box (LaTeX formula rendering, etc)\n- [ ] extract core modules from CLI, to enable re-use\n- [ ] extract filesystem metadata and index that\n- [ ] use filesystem modification times to suggest rebuilding cache file\n- [ ] background process for watching file changes and reindexing\n- [ ] server for viewing \u0026 browsing rendered notes, with search embed\n- [ ] incremental index update (not supported by lunr)\n- [ ] command to set up git to treat index file as binary (see .gitattributes)\n- [ ] webcomponent for embedding search in markdown\n- [ ] add .searchignore file\n- [ ] numeric data types for metadata (\"rating \u003e 4\") _hard_\n- [ ] package as a binary instead of nodejs library\n  - [ ] electron app that acts as a container for background processes and wraps CLI\n- [ ] consider re-licensing as something other than basic MIT\n- [ ] some sort of handling for daily notes/bullet journaling\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexkrolick%2Fsearch-notes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexkrolick%2Fsearch-notes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexkrolick%2Fsearch-notes/lists"}