{"id":16774202,"url":"https://github.com/dragonwocky/psyche","last_synced_at":"2025-03-22T00:30:47.604Z","repository":{"id":44705424,"uuid":"443678366","full_name":"dragonwocky/psyche","owner":"dragonwocky","description":"a drop-in solution for searching documentation","archived":false,"fork":false,"pushed_at":"2022-02-23T20:15:01.000Z","size":2117,"stargazers_count":23,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T06:22:49.192Z","etag":null,"topics":["deno","documentation","documentation-search","hotkeys","indexer","javascript","lume","search","search-engine","sitemap","typescript"],"latest_commit_sha":null,"homepage":"https://deno.land/x/psyche","language":"TypeScript","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/dragonwocky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-02T04:09:00.000Z","updated_at":"2024-02-05T17:27:50.000Z","dependencies_parsed_at":"2022-07-20T20:48:17.037Z","dependency_job_id":null,"html_url":"https://github.com/dragonwocky/psyche","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fpsyche","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fpsyche/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fpsyche/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fpsyche/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dragonwocky","download_url":"https://codeload.github.com/dragonwocky/psyche/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244890102,"owners_count":20527030,"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":["deno","documentation","documentation-search","hotkeys","indexer","javascript","lume","search","search-engine","sitemap","typescript"],"created_at":"2024-10-13T06:48:24.795Z","updated_at":"2025-03-22T00:30:47.303Z","avatar_url":"https://github.com/dragonwocky.png","language":"TypeScript","funding_links":["https://github.com/sponsors/dragonwocky"],"categories":[],"sub_categories":[],"readme":"# 🧠 psyche\n\n**psyche** is a drop-in solution for searching documentation,\ninspired by Algolia's [DocSearch](https://docsearch.algolia.com/).\n\n- It **looks and feels awesome** to use.\n- Searching is **fast, accurate and typo-tolerate**.\n- It can be included in any **static or server-generated** documentation website.\n- It doubles as a **keyboard-navigable sitemap**.\n- It makes registering **site-wide, platform-dependent hotkeys** simple.\n- It's **mobile-friendly**.\n- It supports both **light and dark modes**.\n\nCheck out the [notion-enhancer documentation](http://notion-enhancer.github.io/) for a live demo.\n\n![](psyche.gif)\n\n\u003e **Warning:** psyche is built specifically for searching documentation.\n\u003e It is not built for implementation into other interfaces (e.g. eCommerce)\n\u003e or use with custom data schemes.\n\n## Getting started\n\n### Generating an index\n\nThe psyche client requires a pre-generated index of results to search.\nThis should be an array of `Result` records (see [types.d.ts](./types.d.ts#L10)).\nIndexes are provided to the client programmatically, but should take the\nform of an unformatted/minified `.json` file.\n\nIndexers are plugins/middleware that crawl a site and generate an index,\neither during a build process or on-the-fly if the site is dynamically served.\n\nIndexers for some documentation generators are provided below.\nIf your generator of choice is not yet supported, either open a\n[feature request](https://github.com/dragonwocky/psyche/issues)\nor write your own and open a [pull request](https://github.com/dragonwocky/psyche/pulls).\n\n#### [🔥 Lume](https://lumeland.github.io/)\n\nAdd the following to your `_config.ts` file:\n\n```ts\nimport psyche from 'https://deno.land/x/psyche/indexers/lume.ts';\n\nsite.use(psyche());\n```\n\nThe indexer can be configured by providing a `LumeConfig` object\nas the first argument of the `psyche()` call (see [types.d.ts](./types.d.ts#L131)).\n\nBy default:\n\n- The index will be output to `/search.json`.\n- Pages without `data.section` or where `data.draft = true` will be ignored.\n- Pages will be grouped by `data.section_order` \u0026 sorted by `data.order`.\n- Page titles are accessed from `data.title`.\n- Page sections are accessed from `data.section`.\n- Headings, code blocks, paragraphs and lists within an `\u003carticle\u003e\u003c/article\u003e` element\n  in a page are indexed according to semantic HTML. Other elements (e.g.\n  `\u003cblockquote\u003e\u003c/blockquote\u003e`) are treated as paragraphs. This works best\n  with markdown output.\n\nRead the [page data](https://lumeland.github.io/creating-pages/page-data/)\nand/or [shared data](https://lumeland.github.io/creating-pages/shared-data/)\npages of Lume's documentation to see how to set these properties.\n\n### Including the client\n\nThe psyche client is written in TypeScript. You can either directly import\nit if your site's assets will be bundled by e.g. [ESBuild](https://esbuild.github.io/),\nor import the pre-transpiled and minified JavaScript build.\n\n```js\nimport psyche from 'https://deno.land/x/psyche/client/mod.ts';\n// or\nimport psyche from 'https://deno.land/x/psyche/client/psyche.min.mjs';\n```\n\nThe `psyche` default export is a function that when provided with\na `ClientConfig` object (see [types.d.ts](./types.d.ts#L31)) will\nreturn a `ClientInstance` (see [types.d.ts](./types.d.ts#L107)).\n\nCalling `.register()` on a client instance will insert the component\ninto the document and listen for hotkey presses. The component can\nthen be opened either by calling `.open()` or by pressing `CTRL/⌘ + K`.\n\nE.g.\n\n```js\nconst searchInstance = psyche({\n  theme: { scrollbarStyle: 'square' },\n  index: await fetch('/search.json').then((res) =\u003e res.json()),\n});\nsearchInstance.register();\nsearchInstance.open();\n```\n\n#### Registering hotkeys\n\nTo add a hotkey to the list in the search modal,\nadd it to the `hotkeys` array of psyche's `ClientConfig`\nobject (see [types.d.ts](./types.d.ts#L31)).\n\nFor platform-dependent hotkeys, the named export `platformModifier`\nwill be equivalent to the \u003ckbd\u003e⌘\u003c/kbd\u003e key on MacOS or the \u003ckbd\u003eCTRL\u003c/kbd\u003e\nkey on other platforms.\n\nTo handle hotkeys, provide a `ClientHotkey` object (see [types.d.ts](./types.d.ts#L124))\nto the named export `registerHotkey`. This is a `KeyboardEvent` partial with a few\nadditional properties:\n\n- the `platformModifier` property is equivalent to `metaKey` on MacOS\n  or `ctrlKey` on other platforms.\n- the `onkeydown` property will be called when the key combination is pressed\n  down, passed the triggered `KeyboardEvent` as its first argument.\n- the `onkeyup` property will be called when the key combination is released,\n  passed the triggered `KeyboardEvent` as its first argument.\n\nE.g.\n\n```js\nimport psyche, {\n  registerHotkey,\n  platformModifier,\n} from 'https://deno.land/x/psyche/client/psyche.min.mjs';\n\nregisterHotkey({\n  key: 'l',\n  platformModifier: true,\n  shiftKey: true,\n  onkeydown: (event) =\u003e {\n    event.preventDefault();\n    toggleTheme();\n  },\n});\n\nconst searchInstance = psyche({\n  hotkeys: [{ kbd: `${platformModifier} + SHIFT + L`, label: 'to toggle theme' }],\n});\nsearchInstance.register();\n```\n\n---\n\nChanges to this project are recorded in the [CHANGELOG](CHANGELOG.md).\n\nThis project is licensed under the [MIT License](LICENSE).\n\nTo support future development of this project, please consider\n[sponsoring the author](https://github.com/sponsors/dragonwocky).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragonwocky%2Fpsyche","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdragonwocky%2Fpsyche","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragonwocky%2Fpsyche/lists"}