Skip to content

Commit

Permalink
add additional example and enumerate query params (github#18307)
Browse files Browse the repository at this point in the history
  • Loading branch information
rachmari authored Mar 18, 2021
1 parent 04450ec commit 4702dcd
Showing 1 changed file with 18 additions and 4 deletions.
22 changes: 18 additions & 4 deletions contributing/search.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,26 @@ To see all existing search-related issues and pull requests, visit [github.com/g

## How to search

The site search is part of every version of docs.github.com. On any page, you can use the search box to search the documents we've indexed.
You can also query our search endpoint directly at: https://docs.github.com/search?version=dotcom&language=en&filters=topics:%27oauth%20apps%27+AND+topics:%27github%20apps%27&query=install
The site search is part of every version of docs.github.com. This endpoint responds in JSON format, and fronts Algolia and Lunr. We recommend using this endpoint over directly integrating with Algolia or Lunr, as the endpoint will be more stable. On any page, you can use the search box to search the documents we've indexed.
You can also query our search endpoint directly at:
https://docs.github.com/search?version=<VERSION>&language=<LANGUAGE CODE>&filters=topics:<TOPIC>&query=<QUERY>

- The VERSION can be any numbered GitHub Enterprise Server version (e.g., `2.22`, `3.0`), GitHub AE (`ghae`), or the Free pro team plan (`dotcom`).
- The LANGUAGE CODE can be: `cn`, `de`, `en`, `es`, `ja`, or `pt`.
- TOPIC can be any topics in [the allowed list of topics](/data/allowed-topics.js). The values in the `topics` attribute are **not** case sensitive, so filtering on `GitHub actions` or `github actions` will return the same result. **Note:** Currently, the topics filter only works for the dotcom version in the English language. We plan to expand this search query to other languages and versions in the future.
- Any search QUERY you'd like.

Using the attribute `topics` in your query will only return results that have the matching topic value. You can find a full list of topics in [the allowed topics file](/data/allowed-topics.js). The `topics` attribute is configured as a [`filter only` facet in Algolia](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/). When the topic contains spaces, you must use quotes. For Algolia, [here](https://www.algolia.com/doc/api-reference/api-parameters/filters/#handle-attributes-with-spaces) is an example for filters containing spaces. Algolia also requires [boolean operators](https://www.algolia.com/doc/api-reference/api-parameters/filters) to combine more than one filter.
For example, to filter on the topic `ssh` and the query `passphrases`, you'd use this search query:

This endpoint responds in JSON format, and fronts Algolia and Lunr. We recommend using this endpoint over directly integrating with Algolia or Lunr, as the endpoint will be more stable.
https://docs.github.com/search?version=dotcom&language=en&filters=topics:ssh&query=passphrases

To filter for the topics `oauth apps` and `github apps` and the query `install`, you'd use this search query:

https://docs.github.com/search?version=dotcom&language=en&filters=topics:'oauth apps'+AND+topics:'github apps'&query=install

### Using the topics search filter

Using the attribute `topics` in your query will only return results that have the matching topic value. The `topics` attribute is configured as a [`filter only` facet in Algolia](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/). When the topic contains spaces, you must use quotes. For Algolia, [here](https://www.algolia.com/doc/api-reference/api-parameters/filters/#handle-attributes-with-spaces) is an example for filters containing spaces. Algolia also requires [boolean operators](https://www.algolia.com/doc/api-reference/api-parameters/filters) to combine more than one filter.

## Production deploys

Expand Down

0 comments on commit 4702dcd

Please sign in to comment.