{"id":19692154,"url":"https://github.com/getgrav/grav-plugin-simplesearch","last_synced_at":"2025-04-29T09:31:21.381Z","repository":{"id":19319058,"uuid":"22557240","full_name":"getgrav/grav-plugin-simplesearch","owner":"getgrav","description":"Grav SimpleSearch Plugin","archived":false,"fork":false,"pushed_at":"2025-02-12T16:22:33.000Z","size":1285,"stargazers_count":44,"open_issues_count":50,"forks_count":54,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-04-19T08:07:35.291Z","etag":null,"topics":["grav","grav-plugin","search"],"latest_commit_sha":null,"homepage":"https://getgrav.org","language":"PHP","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/getgrav.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-08-02T20:53:03.000Z","updated_at":"2025-02-12T16:22:37.000Z","dependencies_parsed_at":"2025-04-18T21:25:27.065Z","dependency_job_id":"0d4bd948-8350-4a83-b6f4-7fb14994bb4d","html_url":"https://github.com/getgrav/grav-plugin-simplesearch","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-simplesearch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-simplesearch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-simplesearch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-simplesearch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getgrav","download_url":"https://codeload.github.com/getgrav/grav-plugin-simplesearch/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250387267,"owners_count":21422111,"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":["grav","grav-plugin","search"],"created_at":"2024-11-11T19:12:28.170Z","updated_at":"2025-04-29T09:31:21.341Z","avatar_url":"https://github.com/getgrav.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grav SimpleSearch Plugin\n\n![SimpleSearch](assets/readme_1.png)\n\n`SimpleSearch` is a simple, yet very powerful [Grav][grav] plugin that adds search capabilities to your Grav instance. By default it can search Page **Titles**, **Content**, **Taxonomy**, and also a raw page **Header**.\n\n# Installation\n\nInstalling the SimpleSearch plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.\n\n## GPM Installation (Preferred)\n\nThe simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's Terminal (also called the command line).  From the root of your Grav install type:\n\n    bin/gpm install simplesearch\n\nThis will install the SimpleSearch plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/simplesearch`.\n\n## Manual Installation\n\nTo install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `simplesearch`. You can find these files either on [GitHub](https://github.com/getgrav/grav-plugin-simplesearch) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).\n\nYou should now have all the plugin files under\n\n    /your/site/grav/user/plugins/simplesearch\n\n\u003e NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) plugins, and a theme to be installed in order to operate.\n\n# Config Options\n\nTo effectively use the plugin, you first need to create an override config. To do so, create the folder `user/config/plugins` (if it doesn't exist already) and copy the [simplesearch.yaml][simplesearch] config file in there.\n\n```\nenabled: true\nbuilt_in_css: true\nbuilt_in_js: true\ndisplay_button: false\nmin_query_length: 3\nroute: /search\nsearch_content: rendered\ntemplate: simplesearch_results\nfilters:\n    category:\nfilter_combinator: and\nignore_accented_characters: false\norder:\n    by: date\n    dir: desc\nsearchable_types:\n    title: true\n    content: true\n    taxonomy: true\n    header: false\nheader_keys_ignored: ['title', 'taxonomy','content', 'form', 'forms', 'media_order']\n```\n\nBy creating the configuration file: `user/config/plugins/simplesearch.yaml` you have effectively created a site-wide configuration for SimpleSearch.  However, you may want to have multiple searches.\n\n\u003e NOTE: If you want to search **ALL PAGES** just keep the `filters` section empty.\n\nTo accomplish multiple search types in a single site, you should use **page-based** configuration. This is simple to do, simply provide any or all of the configuration options under a `simplesearch:` header in your page frontmatter.  For example:\n\n```\nsimplesearch:\n    process: true\n    route: @self\n    filters:\n        - @self\n        - @taxonomy: [tag]\n    filter_combinator: and\n```\n\n These page headers will only be taken into account if the search route points to this page.  For example: here the route points to `@self` which in turn resolves to `/blog`.  You can also specify the route explicitly with `route: /blog` if you so choose. This header is within the `/user/pages/blog/blog.md` file.  We will cover this self-controlled form of search handling below.\n\n# Usage\n\nThere are two approaches to using SimpleSearch.\n\n## 1. Standalone Search Page\n\nThis is the traditional approach and involves having a searchbox 'somewhere' on your site. When you search you are shown a new page that displays the search results.  On this page you will see a summary of the results and be able to click a link to visit each applicable page within your site.  Think about how **Google** and other traditional search engines work.\n\nAfter installing the SimpleSearch plugin, you can add a simple **searchbox** to your site by including the provided twig template.  Or copy it from the plugin to your theme and customize it as you please:\n\n```\n{% include 'partials/simplesearch_searchbox.html.twig' %}\n```\n\nBy default the **simplesearch_searchbox** Twig template uses the `route` as defined in the configuration.  The SimpleSearch plugin uses this route and then appends a `query:` parameter to create the following final URL.\n\n```\nhttp://yoursite.com/search/query:something\n```\n\n1. `/search`: This is the **route** setting and it can be changed\n2. `/query:something`: This is the query itself, where `something` is what you are searching for.\n\nThe plugin actively looks for URLs requested that match the configured `route` and if so it intercepts the call and renders the results template as specified by the configuration options, (defaults to `simplesearch_results.html.twig` as provided by the plugin).\n\nWith this approach, the filters control which pages are searched.  You can have multiple taxonomy filters here, and can configure the combinator to require **any** match (via `or`) or require **all** conditions to match (via `and`).\n\nYou can also completely customize the look and feel of the results by overriding the template. There are two methods to do this.\n\n1. Copy the file [templates/simplesearch_results.html.twig][results] under your theme templates `user/themes/_your-theme_/templates/` and customize it.\n\n2. Create your very own results output. For this you need to change the `template` reference in the config (let's say **mysearch_results**). In your theme you would then create the new template under `user/themes/_your-theme_/templates/mysearch_results.html.twig` and write your customizations. This is how it looks by default:\n\n    ```\n    {% extends 'partials/simplesearch_base.html.twig' %}\n\n    {% block content %}\n        \u003cdiv class=\"content-padding\"\u003e\n        \u003ch1 class=\"search-header\"\u003eSearch Results\u003c/h1\u003e\n        \u003ch3\u003eQuery: \"{{ query }}\" - Found {{ search_results.count }} {{ 'Item'|pluralize(search_results.count) }}\u003c/h3\u003e\n\n        {% for page in search_results %}\n            {% include 'partials/simplesearch_item.html.twig' with {'page':page} %}\n        {% endfor %}\n        \u003c/div\u003e\n    {% endblock %}\n    ```\n\n## 2. Self-Controlled Search Page\n\nThis is a new feature of SimpleSearch and it's a very useful and simple way to provide a 'filter' like search of a collection listing page.  In this example, we will assume you have a Blog listing page you wish to be able to search and filter based on a search box.\n\nTo accomplish this, you need to use the page-based configuration as described above, and configure multiple filters, `@self` to use the page's content collection: http://learn.getgrav.org/content/headers#collection-headers\n\n```\ncontent:\n    items: @self.children\n    order:\n        by: date\n        dir: desc\n```\n\nThis will mean the search will only search pages that this page already is using for the collection.  The Items could be anything the page collections support:\n\nFor further help with the `filters` and `order` settings, please refer to our [Taxonomy][taxonomy] and [Headers][headers] documentation.\n\nMultiple filters can be provided, and in order to search in the page's **Tag** field you would add `- @taxonomy: [tag]` as shown in the configuration example above.\n\nThe only thing needed to provide this functionality is a search box that points to the current page and appends the `query` parameter.  You can again simple include the sample `simplesearch_searchbox.html.twig` file or add your own. Because the route is configured to point to the blog page, and because the blog page already iterates over a collection, SimpleSearch will replace the page collection with the search-filtered collection.  No results page is required.\n\n## Performance\n\nSimplesearch is not a full-fledged index-powered search engine.  It merely iterates over the pages and searches the content and title for matching strings.  That's it.  This is not going to result in screaming fast searches if your site has lots of content.  One way to optimize things a little is to change the `search_content` configuration option from `rendered` to `raw`.  This means the `rawMarkdown()` method is used rather than the `content()` method, to retrieve the page content, and in turn means plugin events, markdown processing, image processing, and other time-consuming tasks are not performed.  This can often yield adequate search results without the need for all this extra work. \n\n## Searching Taxonomy\n\nBy default **SimpleSearch** will search in the **Title**, **Content**, and **Taxonomy**.  All taxonomy will be searched unless you provide a **taxonomy filter** either in the page, or in the global plugin configuration:\n\n```\nfilters:\n    - @taxonomy: [tag]\n```\n\nThis will ensure that only **tag** taxonomy types will be searched for the query.\n\n```\nfilters:\n    - @taxonomy: [tag, author]\n```\n\nWill ensure that both **tag** and **author** taxonomy types are searched.\n\nAs **all taxonomy types are searched by default**, in order to stop searching into taxonomies completely simply set the filter to false:\n\n```\nfilters:\n    - '@taxonomy': false\n```\n\n## Ignoring a page\n\nA page can be setup to \"opt-out\" of being included in the search results by setting the following in page frontmatter:\n\n```yaml\nsimplesearch:\n  process: false\n```\n\n## Ignoring accented characters\n\nYou can tell Simplesearch to return a positive value when searching for characters that have an accent. So `éè` for example will be both equivalent to `e`.\n\nTo do so, enable _Ignore accented characters_ in Admin, or manually set `ignore_accented_characters` to true in the plugin configuration.\nThe `en_US` locale must be installed on the server.\n\n# Extending\n\nAs of version `2.3.0` SimpleSearch has a Grav even that allow for integrating into custom logic and adding your own 'pages' into the searchable collection.  Because SimpleSearch utilizes Grav pages for its searching mechanism, your event needs to build fake 'pages' from your data, then you can add to the collection being passed to the event.  Some example psudeo code should help you out:\n\n```php\n    public function onSimpleSearchCollection(Event $event)\n    {\n        $collection = $event['collection'];\n        $locator = $this-\u003egrav['locator'];\n        $pages = $this-\u003egrav['pages'];\n\n        //find all my custom files\n        $finder = new Finder();\n        $data_location = $locator-\u003efindResource(\"user://data/custom-data\");\n        \n        foreach($finder-\u003ein($data_location)-\u003ename('*.json') as $file) {\n            $content = $file-\u003egetContents();\n            $data = json_decode($content, true);\n\n            $header['routes']['default'] = $data['url'],\n            $page = new Page();\n            $page-\u003etitle($data['title']);\n            $page-\u003econtent($data['content']);\n            $page-\u003epath($file-\u003egetPathname());\n            $page-\u003eheader($header);\n\n            // Page needs to be added to Pages inorder to work in Collection\n            $pages-\u003eaddPage($page);\n            // Add the fake page to the collection used to search\n            $collection-\u003eaddPage($page);\n        }\n    }\n```\n\n# Updating\n\nAs development for SimpleSearch continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating SimpleSearch is easy, and can be done through Grav's GPM system, as well as manually.\n\n## GPM Update (Preferred)\n\nThe simplest way to update this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). You can do this with this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:\n\n    bin/gpm update simplesearch\n\nThis command will check your Grav install to see if your SimpleSearch plugin is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type `y` and hit enter. The plugin will automatically update and clear Grav's cache.\n\n\n\u003e Note: Any changes you have made to any of the files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in `user/config/plugins`) will remain intact.\n\n[taxonomy]: http://learn.getgrav.org/content/taxonomy\n[headers]: http://learn.getgrav.org/content/headers\n[grav]: http://github.com/getgrav/grav\n[simplesearch]: simplesearch.yaml\n[results]: templates/simplesearch_results.html.twig\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgrav%2Fgrav-plugin-simplesearch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetgrav%2Fgrav-plugin-simplesearch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgrav%2Fgrav-plugin-simplesearch/lists"}