Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Add documentation search #37
I always wanted to have search capabilities inside the Laravel documentation so I made it.
You can test the live demo here http://laravel.neptos.fr/docs/5.0
You will find a list of differences between the two pull requests at the end of this comment.
Benefits for the end user
How does it works
There's a free index at Algolia that hosts the documentation, when a user does a search we use the Algolia API and then map to the pages and section of the documentation.
The index is populated via an Artisan task (more on this below).
Testing the pull request locally
If you want to test this pull request on your machine, you can do this:
git clone firstname.lastname@example.org:maxiloc/laravel.com.git cd laravel.com git checkout add-documentation-search composer update php artisan serve
Updating the index
When doing documentation updates, to update the relevant Algolia index, do this:
ALGOLIA_ADMIN_KEY=[YOUR_ALGOLIA_ADMIN_KEY] php artisan docs:index
@taylorotwell I am sending you a email with access to the Algolia's dashboard of the index.
Differences with ElasticSearch pull-request (#18)
I cut each page in small parts (h1, h2, ...) and prioritize them in order to have good relevance. It also allows to go directly to the concerning anchor when selecting a suggestion.
This is an autocomplete implementation, which allow a quick access to content using only keyboard and do not need a page load to have the results.
The elastic search solution requires us to host it and maintain it, while Algolia is a SAAS hosted it in 12 different regions.
We already support other community websites like Hackernews search, CDNJS, GrowthHackers or Product hunt. In exchange, we only ask for a "powered by Algolia" in the search results. This pull request adds it too.
If you want to move forward with this implementation, we will of course give you the search account for free as explained before.
Please contact me if you have any question or would like more information.
So I've got this working locally, and it is very nice. However, I am quite concerned about maintaining this custom block parsing logic going forward. If there is ever any change with our documentation parsing or library or logic, etc. everything related to search would break, which gives me some pause.
Can you give me a better idea of what all that is trying to do? Maybe it can be done in a better way?
Hi, thanks for your response.
The main idea for this search was to have the best relevance possible. By cutting the markdown into small pieces, we can then prioritize some blocks like h1, h2 in the search ranking.
This is a different approach to indexing the all markdown/html directly. It generally leads to better relevance.
To do that there is two functions dealing with markdown Blocks :
The \App\CustomParser::getBlocks function
It is a copy Parsedown::lines without the end of the code that convert the $Blocks variable to html. I did not modify anything except cutting the end.
The original function can be found here https://github.com/erusev/parsedown/blob/790066e9a7dbac9b1441005b902531ec9de0ed00/Parsedown.php#L124 (I also added this as a comment in the code)
The App\Services\Documentation\Indexer::indexDocument function
It take the markdown blocs from \App\CustomParser::getBlocks, filter it by ignoring unwanted block like code example and for each one create an object that look like
If the documentation moves from markdown to another format then yes we will maybe have to do some work.
In all cases, I will always be available to help you on this feature.
Let me know what you think.
@taylorotwell I am very exited about the release tomorrow
I just created you a second index called "docs_lumen" if you want the same search on the Lumen documentation.
You will just need to replace in App\Services\Documention\Indexer
private static $index_name = 'docs';
private static $index_name = 'docs_lumen';
And change in laravel.js
var index = client.initIndex('docs');
var index = client.initIndex('docs_lumen');