nikon/docsearch
1
0
Fork 0
Code Activity Actions

Updating front-end documentation

Browse source
This commit is contained in:
Pixelastic 2018-08-14 17:14:45 +02:00
parent b71f67cb50
commit e40381f865
7 changed files with 222 additions and 174 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/config.json
View file

@ -5,7 +5,9 @@
"url": "https://community.algolia.com/docsearch",
"repo": "https://github.com/algolia/docsearch"
},
"placeholders": {},
"placeholders": {
"docSearchJSVersion": "2"
},
"sidebar": [
{
"title": "Essentials",
@ -52,8 +54,8 @@
"url": "styling.html"
},
{
"title": "Events",
"url": "events.html"
"title": "Behavior",
"url": "behavior.html"
}
]
},

7
docs/src/_styles/highlight.css
View file

@ -29,4 +29,11 @@ pre code.hljs {
.hljs-literal {
@apply .text-nebula;
}
/* CSS */
.hljs-selector-class {
@apply .text-saturn-2;
}
.hljs-attribute {
@apply .text-saturn;
}
}

BIN
docs/src/assets/default-colorscheme.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 21 KiB

113
docs/src/behavior.md Normal file
View file

@ -0,0 +1,113 @@
---
layout: two-columns
title: Dropdown Behavior
---
`docsearch.js` is a wrapper around the [autocomplete.js][1] library. This
library will listen to keystrokes in the search input, query Algolia and display
the results in a dropdown. Everything is already configured for you to work with
DocSearch, but it also exposes configuration options you can use to go even
further.
## `appId`
If you're running the DocSearch crawler yourself, you'll need to define your
application ID using the `appId` key. If you're using the free hosted version,
you don't need to add anything.
```javascript
docsearch({
appId: '<YOUR_CUSTOM_APP_ID>',
[…],
});
```
## `handleSelected(input, event, suggestion)`
This method is called when a suggestion is selected. By default, DocSearch will
redirect the browser to the page matching part of the page, but you can override
it to add your own behavior.
The method is called with three arguments:
- `input`, a reference to the search `input` element. It comes with the `.open()`,
`.close()`, `.getVal()` and `.setVal()` methods.
- `event`, the actual event triggering the selection. This can come from a click
or a keyboard navigation.
- `suggestion`, the object representing the current selection.
```javascript
docsearch({
[…],
handleSelected: function(input, event, suggestion) {
}
});
```
## `queryHook(query)`
This method will be called on every keystroke to transform the typed keywords
before sending them to Algolia. By default, it does not do anything, but we
provide this hook for you to add your own logic if you want.
```javascript
docsearch({
[…],
queryHook: function(query) {
// Transform query, and then return the updated version
}
});
```
## `transformData(suggestions)`
This method will be called on all suggestions before displaying them. It
doesn't do anything by default, but we provide this hook if you want to add your
own logic.
```javascript
docsearch({
[…],
transformData: function(suggestions) {
// Transform the list of suggestions, and the return the updated list
}
});
```
## `autocompleteOptions`
You can pass any option to the underlying `autocomplete.js` instance by using
the `autocompleteOptions` parameter. You will find all the list of all available
value in its [the official documentation][2].
You can also listen to `autocomplete` events through the `.autocomplete`
property of the `docsearch` instance.
```javascript
const search = docsearch({
[…]
autocompleteOptions: {
// See https://github.com/algolia/autocomplete.js#options
}
});
// See https://github.com/algolia/autocomplete.js#custom-events
search.autocomplete.on('autocomplete:opened', event => {
});
```
## `algoliaOptions`
You can pass options to the Algolia API by using the `algoliaOptions`
key. You will find all Algolia API options in their [own documentation][3].
```javascript
docsearch({
algoliaOptions: {
// See https://www.algolia.com/doc/api-reference/api-parameters/
}
});
```
[1]: https://github.com/algolia/autocomplete.js
[2]: https://github.com/algolia/autocomplete.js#options
[3]: https://www.algolia.com/doc/api-reference/api-parameters/

32
docs/src/dropdown.md Normal file
View file

@ -0,0 +1,32 @@
---
layout: two-columns
title: Dropdown
---
To add the dropdown of results next to your search input, you'll have to include
the `docsearch.js` library into your website as per the following example. Your
`apiKey` and `indexName` credentials will be given to you as soon as we've
created your config.
```html
<!-- Before the closing </head> -->
<link rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/docsearch.js@{{docSearchJSVersion}}/dist/cdn/docsearch.min.css"
/>
<!-- Before the closing </body> -->
<script
src="https://cdn.jsdelivr.net/npm/docsearch.js@{{docSearchJSVersion}}/dist/cdn/docsearch.min.js"></script>
<script>
docsearch({
// Your apiKey and indexName will be given to you once
// we create your config
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>',
// Replace inputSelector with a CSS selector
// matching your search input
inputSelector: '<YOUR_CSS_SELECTOR>',
});
</script>
```

107
docs/src/events.md
View file

@ -1,107 +0,0 @@
---
layout: two-columns
title: Configuring the search results
---
// TODO
DocSearch is a wrapper around the [autocomplete.js](https://github.com/algolia/autocomplete.js) library that gets its
results from the Algolia API. As such, you can use any options provided by this project and by [the Algolia API](https://www.algolia.com/doc/api-reference/).
## Autocomplete options
You can pass any options to the underlying `autocomplete` instance through
the `autocompleteOptions` parameter. You will find all `autocomplete` options in
its [own documentation](https://github.com/algolia/autocomplete.js#options).
You can also listen to `autocomplete` events through the `.autocomplete`
property of the `docsearch` instance.
```javascript
var search = docsearch({
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>',
inputSelector: '<YOUR_INPUT_DOM_SELECTOR>',
debug: true,
autocompleteOptions: {
// See https://github.com/algolia/autocomplete.js#options
// For full list of options
}
});
// See https://github.com/algolia/autocomplete.js#custom-events
// For full list of events
search.autocomplete.on('autocomplete:opened', function(e) {
// Do something when the dropdown menu is opened
});
```
## Docsearch Options
### handleSelected
We already bind the autocomplete:selected event inside the docsearch.
If you want to replace the default behavior you can pass the `handleSelected` option.
```javascript
var search = docsearch({
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>',
inputSelector: '<YOUR_INPUT_DOM_SELECTOR>',
handleSelected: function (input, event, suggestion) {
}
});
```
### queryHook
If you want modify the query before it is sent to Algolia you can pass the `queryHook` option.
```javascript
var search = docsearch({
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>',
inputSelector: '<YOUR_INPUT_DOM_SELECTOR>',
queryHook: function (query) {
return query + "_modified";
}
});
```
### transformData
If you want to modify the hits before displaying them you can make use of the
`transformData` option
```javascript
var search = docsearch({
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>',
inputSelector: '<YOUR_INPUT_DOM_SELECTOR>',
transformData: function (hits) {
// modify hits
return hits;
}
});
```
### Algolia options
You can also pass any specific option to the Algolia API to change the way
records are returned. You can pass any options to the Algolia API through
the `algoliaOptions` parameter.
```javascript
docsearch({
appId: '<APP_ID>', // if you are running the crawler yourself
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>',
inputSelector: '<YOUR_INPUT_DOM_SELECTOR>',
algoliaOptions: {
hitsPerPage: 10
}
});
```
You will find all Algolia API options in its [own documentation](https://www.algolia.com/doc/api-reference/api-parameters/).

129
docs/src/styling.md
View file

@ -1,81 +1,82 @@
---
layout: two-columns
title: Customize autocomplete styles
title: Styling DocSearch
---
// TODO
DocSearch default colorscheme comes in grey colors with blue highlight.
## Attribution
![Default colorscheme](./assets/default-colorscheme.png)
We're happy to provide DocSearch free of charge for your site, and you're
welcome to customize that experience in a way that works for you; all we ask is
that Algolia be attributed within the search context. For example, in the
default implementation, we place a small "Search by Algolia" logo in the
corner. If you prefer to roll your own UX, you'll need to make sure that this
logo is included in your implementation as well.
This theme works well with most websites, but we encourage you to style it to
your own colors. This can be achieved by overriding the CSS classes used by the
default theme.
## Default styling
The default colorscheme is white and gray:
![Default colorscheme](https://community.algolia.com/docsearch/assets/images/default-colorscheme.png)
To update the colors to suit your website, you just need to override a few
colors. Here is an example of a CSS file that you can use as a basis to
set white and purple colors.
The following annotated example will help you style each part:
```css
/* Bottom border of each suggestion */
.algolia-docsearch-suggestion {
border-bottom-color: #3A3DD1;
}
/* Main category headers */
.algolia-docsearch-suggestion--category-header {
background-color: #4B54DE;
}
/* Highlighted search terms */
.algolia-docsearch-suggestion--highlight {
color: #3A33D1;
}
/* Highlighted search terms in the main category headers */
.algolia-docsearch-suggestion--category-header .algolia-docsearch-suggestion--highlight {
background-color: #4D47D5;
}
/* Currently selected suggestion */
.aa-cursor .algolia-docsearch-suggestion--content {
color: #272296;
}
.aa-cursor .algolia-docsearch-suggestion {
background: #EBEBFB;
/* Match title (eg. Bootstrap CDN) */
.algolia-docsearch-suggestion--title {
font-weight: bold;
color: black;
}
/* For bigger screens, when displaying results in two columns */
@media (min-width: 768px) {
/* Bottom border of each suggestion */
.algolia-docsearch-suggestion {
border-bottom-color: #7671df;
}
/* Left column, with secondary category header */
.algolia-docsearch-suggestion--subcategory-column {
border-right-color: #7671df;
background-color: #F2F2FF;
color: #4E4726;
}
/* Match description (eg. Bootstrap currently works...) */
.algolia-docsearch-suggestion--text {
font-size: .8rem;
color: gray;
}
/* Match category (eg. Downloads) */
.algolia-docsearch-suggestion--subcategory-column {
color: gray;
}
/* Match main category (eg. Getting Started) */
.algolia-docsearch-suggestion--category-header {
color: darkgray;
border: 1px solid gray;
}
/* Highlighted text */
.algolia-docsearch-suggestion--highlight {
color: blue;
}
```
## Debugging
If you want to inspect the dropdown markup with your browser tools, you should
add `debug: true` to your `docsearch` call to prevent it from closing on
inspection.
```javascript
docsearch({
[…],
debug: true
});
```
## Other considerations
Currently selected suggestion are wrapped in a `.ds-cursor` class. This means
that you can use `.ds-cursor .algolia-docsearch-suggestion--content` to style
the currently selected suggestion for example.
On small screens, DocSearch reverts to a single column layout, while the
two-column layout shown in the screenshot is only used on larger screens. You
can media queries (for example `@media (min-width: 768px) {}`) to target one or
the other display.
We ask you not to try to hide the _search by Algolia_ logo through CSS, as its
display is mandatory if you're using the free hosted version of DocSearch.
## Advanced styling
If you want to do heavy changes to the way results are displayed, you might find
it easier to directly edit the `scss` files in this repository.
If you want to more heavily style the results, feel free to have a look at the
[SCSS source code](https://github.com/algolia/docsearch/tree/master/src/styles).
`_variables.scss` contains all the default colors, sizing and breakpoints.
[`_variables.scss`](https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss)
contains all the color, breakpoints and size definitions while
[`main.scss`](https://github.com/algolia/docsearch/blob/master/src/styles/main.scss)
holds the structure of the display.
You can regenerate the whole final `css` file from those `scss` files by running
`npm run build:css`. The resulting files will be found in `./dist/cdn/`.
All you have to do now is change the `link` tag that was loading the default
styling from our CDN, to one that is loading your newly compiled file.
You can generate your own CSS file by cloning the repo and running `yarn run
build:css`. The resulting file will be generated in `./dist/cdn`, and should be
used instead of the default one.