Creation of documentation on how to implement js-search with gatsby #11030
Conversation
update gatsby remote
updating gatsby remote repo
…nd change to the side bar file
|
Hi, thanks for the work on that! I didn't go through the doc itself yet but have a comment on your example: IMO you should completely remove the |
LekoArts
added
the
type: documentation
|
I left the semantic ui part, just for styling purposes, reading it now after some time it sounds a bit overboard. With that, it's being removed and the document and example updated as we speak. Thanks for the feedback |
|
Any feedback on this? Is there anything that needs to be changed? |
|
conflicts that are popping up are due to this and has i did not want to intrude in someone else work, i left as is. The files were linted. Some feedback would be appreciated |
|
Closing this pull request and removing the branch, as it seems there's no intention on merging this or anything else.....If someone more capable is will to pick it up, have fun |
There was a problem hiding this comment.
Hey @jonniebigodes this is a great start (also thanks for your patience on the review side of things) 👍
I ran through the tutorial and have added some comments. Having thought about it a bit, I wonder if removing some features from the example site would make the tutorial clearer. At the moment it feels like a mix between demonstrating js-search features and using js-search with Gatsby.
I think that focussing down on the using js-search with Gatsby side will make it easier to understand the example and follow along with the tutorial.
Once someone has run through the tutorial they'd be in a good spot to hop over to the js-search docs which covers specific js-search features really nicely.
For example, removing the title, author and remove stop words checkboxes, along with removing the strategy and sanitiser select boxes would make the code search implementation a fair bit shorter. What do you think?
| Inside that folder, create a new Gatsby website using a starter template, using the command below: | ||
|
|
||
| ```bash | ||
| npx gatsby new jsSearchExample https://github.com/gatsbyjs/gatsby-starter-default |
There was a problem hiding this comment.
nice use of npx :) what do you think about changing the directory name to all lowercase? No big deal either way but I think that will more closely match other guides in the site.
There was a problem hiding this comment.
Why not propose a compromise, instead of all lowercase how about js-search-example, reason being because someone, let's call it the better half, while taking a peak at the document, she said and i quote, "Change the folder name to a hyfenated name, because and you know me i'm not a tech expert, if i was to pickup on this i would like the folder name to be as humanly readable as possible, even not being a native english speaking person" and relationship aside, she's got a point in there. 😉
There was a problem hiding this comment.
@jonniebigodes that sounds great! I think we should generally use dash-case (often called kebab-case), so yeah, good call!
| After all of this is done the actual implementation can be started. | ||
|
|
||
| Both approaches documented here are fairly generalistic so that most of the options offered by the library can be experimented with. | ||
|
|
There was a problem hiding this comment.
This could be a good spot to add a couple of lines about the two approaches, describing when either approach might be more appropriate.
You've got this info at the end of the second approach section already 👍, moving it up here means people could choose an approach before reading through the whole guide.
| }) | ||
| } | ||
| /** | ||
| * es6 fat arrow function to instantiate the search engine |
There was a problem hiding this comment.
I think you could make these comments clearer by removing the es6 fat arrow function section and adding a note to the Prerequisites section that you'll need some familiarity with es6 syntax like arrow functions.
|
|
||
| The approach documented below is a fairly simple one, by having the component fetch the data and create the search engine. | ||
|
|
||
| Start by creating a file in the `components` folder, for this particular case the name will be `SearchContainer.js` and inside of it the following baseline code will be added to get started: |
There was a problem hiding this comment.
Add src/ to the folder name and re-arrange to make a little shorter?
| Start by creating a file in the `components` folder, for this particular case the name will be `SearchContainer.js` and inside of it the following baseline code will be added to get started: | |
| Start by creating a file named `SearchContainer.js` in the `src/components/` folder, then add the following code to get started: |
| "gatsby-plugin-manifest": "^2.0.9", | ||
| "gatsby-plugin-offline": "^2.0.16", | ||
| "gatsby-plugin-react-helmet": "^3.0.2", | ||
| "gatsby-plugin-sharp": "^2.0.14", |
There was a problem hiding this comment.
What do you think about basing this example on gatsby-starter-hello-world instead of gatsby-starter-default? The hello world starter has less dependencies and a smaller gatsby-config.js file, which would make it easier to see which parts are related to setting up js-search.
|
|
||
| Note: | ||
|
|
||
| For brevity purposes, most of the component implementation is omited, with the exception of the `searchData()` function, as this one is responsible for making the search, also the implementation of the `DataTable` component and the page holding this component is not shown. The full code of this example is available [in the js-search repo](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-js-search). |
There was a problem hiding this comment.
I like how you've highlighted the relevant parts of the code in the tutorial here. But I can see this part being confusing for someone that's followed along so far, I got a bit stuck working out which files I needed to copy from the example.
An approach that could make this clearer is to reduce the amount of files used in the example site. So you could do something like this:
- delete
search.cssand apply those styles inline in the DataTable.js component - Move the code from DataTable.js into SearchContainer.js, and then delete the DataTable.js file
Which might not be strictly best practice, but we can add comments explaining how you'd do it in a "real" site, and it'll make the follow up instructions shorter.
Doing this means that someone following this tutorial only needs to copy components/SearchContainer.js and then edit pages/index.js to get their version into a working state.
Then the instructions here can clearly describe which files should be copied from the example site to your local site. After making the previous changes, this could be something like To get this running in your site, copy the SearchContainer.js file to your site, and then update the file pages/index.js [as shown here](#)
Edit: I added some more thoughts about tightening up this section in the overall PR comment.
| export default ClientSearch | ||
| ``` | ||
|
|
||
| The code used in here is almost identical to the one documented in the first approach and for the same reason stated in the first approach, here also the full implementation will not be shown. |
There was a problem hiding this comment.
Similar to my earlier comment, let's make it very clear how to get from this step of the tutorial to a working local site:
- combine files if possible
- clearly describe which files should be copied to your local site
- mention starting the site with
gatsby developand the url to visit
|
|
||
| ## Setup | ||
|
|
||
| Let's start by creating a new Gatsby site to work with. Open up a terminal and create the folder that you'll use for this project: |
There was a problem hiding this comment.
Part of the Gatsby Style Guide is to use "you" as the pronoun in the docs. Here's an explanation of how to make this change and why! https://www.gatsbyjs.org/docs/gatsby-style-guide/#use-you-as-the-pronoun
|
|
||
| For brevity purposes, most of the component implementation is omited, with the exception of the `searchData()` function, as this one is responsible for making the search, also the implementation of the `DataTable` component and the page holding this component is not shown. The full code of this example is available [in the js-search repo](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-js-search). | ||
|
|
||
| ## Second approach |
There was a problem hiding this comment.
I wonder if there's a more precise headers than "first approach" and "second approach". Because sometimes people share URLs with people and the URL will look more readable the headers are specific.
|
By the time you'll be reading this. This branch will be closed and deleted, this due to the fact the probably #10772 and closing and re-opening the pull request introduced some issues with my fork. While trying to commit the updated document and the example, i'm presented with the following:
Tried updating my fork, issued |
|
Note: this work was continued in #11505 |
Description
This pull request creates a first draft on the documentation of client side search with js-search and gatsby. Also an accompanying example is provided, and the change to the side bar file to reflect the changes.
cc @shannonbux @DSchau
Both are cced to this, one for the technical part and the other for the documentation aspect side of things if you both don't mind.
Hoping for some feedback on your part.
Related Issues