Search feature

[Grummfy]

Hi, I will better if there is a search area in the documentation.

Possible solution :

• a simple google/bing/whatever search box area
• using https://github.com/olivernn/lunr.js be we need in this case an indexer
• there is also externals crawler (that cost some money) that generate index or index + search
• you can be inspire by this kjekyll plugins : https://github.com/slashdotdash/jekyll-lunr-js-search
• there is also this : http://tapirgo.com/

There is probably more, the result I get up, is just by searching a couple of minute on google.

[mnapoli]

Hi, good idea.

I think we could do that (we could create an index of Markdown files, and maybe their titles and/or content). This is not a high priority for now as it would require some work, but definitely a valid idea ;)

In the meantime, if people manage to get a quick solution working (e.g. as you said with Google Search) let other people know in here!

[mnapoli]

Merged #110 into this issue, copying the comment:

This may be a crazy thing to suggest, but the only (and I do mean only) thing missing from Couscous is the ability to search within the docs. Obviously, server-side tech is right out, since it's hosted on Github Pages, but what if the build process churned out a one-page file that we could feed into Javascript, which could then provide a type-ahead type of searching, where the results point to the appropriate page?

For smaller document sets, it probably wouldn't be very useful, but for docs with a lot of files, this could be a great feature.

For example, the docs I'm using Couscous for, http://docs.snipeitapp.com, are on the longer side, and once the user's manual gets added, they're only going to get longer.

I've only ever seen this type of thing in generators to work from a single page .md file, though, so maybe the DOM overhead from a javascript component would be too much.

[snipe]

Maybe something like Tipue in the template? We'd just need to generate the JavaScript object if using it in static mode (which is of course the time-consuming bit)

http://www.tipue.com/search/docs/?d=1

If it was used in live mode (versus static), we wouldn't even need to generate that object tho. http://www.tipue.com/search/docs/?d=5

[snipe]

FYI, I got Tipue working on my docs: http://docs.snipeitapp.com/search.html?q=config

It's not all polished yet, but it's getting there. Nice middle-ground for search without backend scripts.

[snipe]

Sorry for all the posts. I ended up writing a blog post about my setup which I thought you might like. http://snipe.net/2015/07/sexy-documentation-from-markdown-with-couscous-and-tipue-on-github-pages/

[mnapoli]

Wow awesome! Thanks!

[snipe]

[wysow]

@snipe Thanks, that's a cool feature indeed!

[snipe]

@wysow My pleasure!

[mobula9]

:+1:

[mnapoli]

I think a very good candidate here would be Aglolia's DocSearch: https://community.algolia.com/docsearch/

Basically you give them your website's URL, they crawl it, you insert their search bar/Javascript and you're done.

[mobula9]

A nice and easy way indeed. But the documentation should be public but it's unfortunately not my case.

[bobmulder]

Does it work dynamically? Else I would suggest to use a built-in library/tool

[mnapoli]

@lucascherifi indeed it wouldn't work with private documentation.

@bobmulder What do you mean by "dynamically"?

I have registered for setting up the search for http://php-di.org we'll see how it goes.

[bobmulder]

Sorry I wasn't clear. I don't get how the process works. Do I have to register at docsearch everytime when I do couscous deploy, or will I register only once, and will it work dynamically on new deploys?

[mnapoli]

You register once. It doesn't seem automated from what I see, someone at Algolia had a look at the website and its HTML/CSS structure to configure on their crawler where the menu is, where are the titles, etc. I guess they crawl the website periodically (every week ?).

[bobmulder]

Ah okay. Sounds good! In that case we can do it on ourselves, and add probably some docs to the couscous website...

[mnapoli]

Good news, I just finished integrating the search in http://php-di.org

You can find the pull request here: https://github.com/PHP-DI/PHP-DI/pull/407

It works using Algolia. Styling the popup was a bit hard but it works really well.

[cyberbit]

@mnapoli It's so pretty! :heart_eyes:

[wysow]

@mnapoli Good job! I'm wondering if we could add a default search engine based on that in default Couscous templates (using couscous.yml to define the api key and other parameters)?

[mnapoli]

@wysow I don't think it would be very useful because adding the JS is the easiest part. Here is a summary of what I did:

• signup on Algolia's website
• get an answer, tech people set up a crawler for the website
• add CSS classes in order for the documentation menu to be friendly to their crawler (several back and forth) - that was asked by Algolia by email
• create a search input
• paste the JS + CSS
• optional: customize the design of the search results

I think it would be better as documentation, since only a very small part of it can be automated. It was still fairly easy though, I would recommend people to use it.

[wysow]

OK got it, seems doable like this for sure, let's go for some documentation... (and maybe implementation of it for Couscous website itself ;))

[bobmulder]

Compared to Mkdocs, this is still 'too much' work to do to get searching ;). Don't know how they managed to do it, but it's defaultly integrated... Would be great to have that too, but this discussion is fired before, so I agree to this suggestion. Would be great to provide some docs for it?

[mnapoli]

@bobmulder They seem to be using Tipue, so I guess they build a JSON index file and then feed it to the JS search engine (like suggested in this issue initially).

I agree Algolia is a little bit more work, but it works right now ;) If anyone wants to add search with Tipue that would also be an awesome addition.

[snipe]

I have a tutorial on using Tipue with Couscous here, if it helps anyone: http://snipe.net/2015/07/sexy-documentation-from-markdown-with-couscous-and-tipue-on-github-pages/

[bobmulder]

I think its worth to add usage of Algolia to the documentation and close this one? ;)

[moqmar]

You might want to try my Mintlook template (https://github.com/moqmar/mintlook-couscous), it uses js-search and an indexer to provide a simple search function.