Wilson Mar bio photo

Wilson Mar

Hello!

Calendar YouTube Github

LinkedIn

Search within Hyde format Jekyll websites

Add a feature-rich search box in your JAM stack website

US (English)   Norsk (Norwegian)   Español (Spanish)   Français (French)   Deutsch (German)   Italiano   Português   Estonian   اَلْعَرَبِيَّةُ (Egypt Arabic)   Napali   中文 (简体) Chinese (Simplified)   日本語 Japanese   한국어 Korean

Overview

The objective of this article is for you to implement these use cases (click on the underlined items to go straight there):

https://wilsonmar.github.io/jekyll-with-algolia-search = https://goo.gl/UWKgTu

  1. Test drive search on a demo site online.

    The site is built with Jekyll and can perform text search on pre-defined text content.

  2. Get a sample theme on your local machine working with search queries.

    We setup your machine with Jekyll and Ruby, then clone a fork of a famous Jekyll theme adapted with search capabilities.

  3. Edit the repo so your own posts are indexed.

    We obtain API keys for a new account on the search service and use it to index new posts we add.

  4. Add search features to another theme.

    We deep dive into the theme to add JavaScript, CSS, and HTML.

Before we dive into Alogolia, know this:

Other options to add search capabilities on a Jekyll site:

Alas, [4:50] near the end of this 5-minute video:

“Where it really falls down is if you have a large site, you need all your search data in a JSON file which has to be downloaded by the client. So if you have hundreds of blog posts, it’s going to be really slow if you try to implement it using lunr.”

Search in Azure

Adding Search Abilities to Your Apps with Azure Search (cloud) 2h 55m video by Chad Campbell (@ChadCampbell, ecofic.com) explains natural language processing for 35 languages (such as searching for “went” when the request is for “go”) and Geospatial around a point or within an area.

But scalability means manual editing in the Azure Portal or programming Azure Search Management APIs.

Use Scoring Profile to align searches.

Test drive search on Algolia’s Jekyll-Hyde theme’s demo site online

  1. Click this link to go to our theme’s demo website on-line:

    http://community.algolia.com/algoliasearch-jekyll-hyde/

    The formatting of this site is what you’ll have as YOUR blog after following instructions in this tutorial.

    Search Demo steps

  2. Type in the search field a single letter such as “L”.

    • Do results appear as you type? It should.

    • Do you need to click a submit button? No.

    • Are results highlighted within the normal presentation rather than with a different format, such as with Bing or Google search?

  3. Click another link (Home) and try search term “Love craxy” (with a capital letter and a misspelling).

    • Is it “typo tolerant” (“crazy” is found even though it was typed in wrong as “craxy”).

    • Are capital letters and lower case letters equivalent?

    Thus, as far as search goes, the theme presented is rather complete. Well, almost.

    404 Search Redirect

  4. Change the URL to a post that should not exist, such as:

    http://community.algolia.com/algoliasearch-jekyll-hyde/whatever

Missing features

We are using a pre-formatted theme rather than design-your-own, which takes much more time and expertise.

Features not in the theme would need to be added.

Get it working locally

Here are the steps setup your own free static website that provides a search box:

  1. Create a GitHub account
  2. Clone a Jekyll template
  3. Install Ruby, Jekyll, Build gems
  4. Run website locally
  5. Create a Shell Script to Run Jekyll Locally
  6. Customize website locally
  7. Update Alogria code locally

The architectural components is call the JAM stack, with JAM standing for JavaScript, APIs, and Markup. The order of the components has no significance (there had to be a vowel in the second letter).

JAM is a fast-growing stack for building websites and apps:

  • No database servers that take time to retrieve

  • No construction of web pages to respond to a request

  • Markup in text files within GitHub for version control
  • Markup files are pre-processed into display-ready HTML

  • HTML files can be stored on various servers around the world in a CDN

  • JavaScript calls APIs for any moving parts (such as retrieving personalization data)

Create a GitHub Account

In this tutorial, we refer to your_account as the account name you created in GitHub.

If you already have an account, skip this section.

  1. Click on this URL to open an internet browser to:

    github.com

  2. Sign-up with a user name you pick (one that’s not already taken).

    NOTE: The remainder of this tutorial refers to “acme” in place of YOUR real user/account name.

  3. Confirm your email.

Fork and rename template altered by Alogolia

Templates provide pre-formatted CSS and JavaScript. Themes are available from a variety of sources.

We like Jekyll over WordPress, Drupal, and other frameworks because unlike them others, Jekyll’s blog entries are stored in text files rather in a database. This makes it easier to switch Jekyll themes.

The theme we are using in this tutorial is based on a fork of the Hyde theme template, which is among the most popular partly because it is created by the legendary Mark Otto, Director of Design at GitHub.

  • Mobile friendly design and development

  • Easily scalable text and component sizing with rem units in the CSS

The steps:

  1. Click the link below to open an internet browser with our base theme:

    https://github.com/algolia/algoliasearch-jekyll-hyde

    This theme adds a search box to the Hyde theme by adding additional HTML, CSS, configuration settings, and JavaScript programming.

    We will examine each change below.

  2. Click its Fork button to put it under your GitHub account.

  3. Click the Settings tab to rename the repo, as your_account_name.github.io.

    In other words, if your account name is “acme”, you would rename the repo to acme.github.io.

    NOTE: “github.io” means the site is hosted by GitHub, which does not charge (unlike GoDaddy or other hosting provider).

    PROTIP: Sites hosted on GitHub.io can still have a custom name such as “acme.com”.

Next, we’ll download the repository.

Install Git Client

There are several choices.

  • Mac machine already have a command-line Git client.

  • Follow this website to install Git in Windows

Create a local repo

  1. Open a Terminal Shell Window on the Mac or cmd program on Windows.

  2. PROTIP: Create a folder path to clone (create) repositories into.

    mkdir ~/gits
    cd gits

    Repos are created within this folder.

  3. PROTIP: Create a folder to hold all Git repositories from your account.

    And change directory into it:

    mkdir ~/gits/your_account
    cd your_account

    On Mac and Linux, the ~ (tilde) character designates the current user’s home folder.

  4. Clone from your_account on GitHub:

    git clone https://github.com/your_account/your_account.github.io

  5. View folder.

    cd your_account.github.io

    NOTE: Cloning creates .git folder that contains all the history in the creation of the template. This file is what enables Git version control.

  6. Compare this against the standard structure.

    Notice the .jekyll-metadata entry keeps the file’s data local. It will NOT be sent back up to GitHub.

  7. Use a text editor to view the .gitignore file.

    The presence of the _site line means that the _site folder generated will NOT be sent back up to GitHub because GitHub will generate its own _site folder.

  8. Use a text editor to create a _config-dev.yml file containing:

    # Develop override settings
url: http://localhost:4001

Install Ruby and Jekyll, Build gems

Text in Jekyll sites are written in “Markdown” format which Jekyll converts to HTML that site vistors download and display on their internet browsers.

The programming for Jekyll to do that is written in the Ruby programming language.

  1. Install the Ruby program compiler on a Mac

    Alternately, install Ruby on Windows.

    Gems contain Ruby programs in a way that can be easily installed.

  2. Install Jekyll as a Ruby gem:

    
gem install jekyll

    This automatically install dependencies.

  3. Use a text editor to open the Gemfile.

    source 'https://rubygems.org'

gem 'jekyll', '~> 2.5'

group :jekyll_plugins do
  gem 'algoliasearch-jekyll', '~> 0.4'
end

    NOTE: If you are adding search capability to an existing site, you would add gem specifications to this file.

  4. Click the URL to visit:

    NOTE: Gems specified are pulled from the Rubygems website.

  5. Search for algoliasearch-jekyll:

    https://rubygems.org/gems/algoliasearch-jekyll/

    The development dependencies are libraries used during code programming:

    • coveralls ~> 0.8 takes json-cov output into stdin and POSTs to coveralls.io
    • flay ~> 2.6
    • flog ~> 4.3 light-weight configurable front-end logger
    • guard-rspec ~> 4.6
    • jeweler ~> 2.0
    • rspec ~> 3.0
    • rubocop ~> 0.31
    • simplecov ~> 0.10

    Run-time dependencies are what needs to be specified in the Gemfile:

    • algoliasearch ~> 1.4
    • appraisal ~> 2.1.0
    • awesome_print ~> 1.6
    • json ~> 1.8
    • nokogiri ~> 1.6
    • verbal_expressions ~> 0.1.5

  6. In a Terminal window, have dependency gems automatically fetched based on the Gemfile and dependencies:

    bundle install

    Install is the default action.

    NOTE: The Gemfile.lock file generated defines the version being used of each gem.

Run Jekyll Locally

  1. To ensure you have a base version that works locally, run:

    bundle exec jekyll serve --config _config.yml,_config-dev.yml --port 4001

    The sample response:

             Source: /Users/mac/gits/acme/acme.github.io
    Destination: /Users/mac/gits/acme/acme.github.io/_site
   Generating...
                 done.
 Auto-regeneration: enabled for '/Users/mac/gits/acme/acme.github.io'
 Server address: http://127.0.0.1:4001/
  Server running... press ctrl-c to stop.

    If an error message appears about port 4000 (the default), it may be because two dashes need to precede the port parameter keyword.

    On a Mac, “ctrl-c” means hold down the control key and press C to stop.

    NOTE: A _site folder should now be generated.

  2. Switch to an internet browser to open the server address:

    http://127.0.0.1:4001

    BTW, documentation on all configuration options:

Create a Shell Script to Run Jekyll Locally

PROTIP: Create a script instead of typing in the long command, to save time and avoid mistakes.

Mac and Linux Shell Script

  1. Use a text editor program to create a file named 4001.sh</strong>.

  2. Save the file in the root folder of the Jekyll repository.

  3. Open a Terminal instance and navigate to that repository.

  4. Define run permissions:

    chmod a+x 4001.sh

Windows Shell Script

  1. Use a text editor program to create a file named 4001.cmd</strong>.

  2. Save the file in the root folder of the Jekyll repository.

  3. Open cmd program and navigate to that Jekyll folder.

Run script

Run script on MacOS

  1. Open a Terminal instance to run it:

    ./4001.sh

  2. View site again.

Run script on Windows

  1. Run it in a command window:

    4001.cmd

  2. View site again.

Update Alogria code locally

Since Algoria is good enough to update its example over time to reflect for changes by authors of the Jekyll base and the Hyde template, you’ll need to update the Aloglia sample, but without messing without disturbing your configuration changes.

  1. PROTIP: Make a zip of your folder so you’ll have an easy fall-back.

  2. In a command-line window, ensure there is a remote:

    git remote -v

    Expect:

    upstream	https://github.com/algolia/algoliasearch-jekyll-hyde (fetch)
upstream	https://github.com/algolia/algoliasearch-jekyll-hyde (push)

    If the above does not appear:

    git remote add upstream https://github.com/algolia/algoliasearch-jekyll-hyde

    Verify the remote again.

  3. Use Git to fetch branches and their contents (with history):

    git fetch upstream -v

    Sample response:

    From https://github.com/algolia/algoliasearch-jekyll-hyde
        * [new branch]      gh-pages   -> algolia/gh-pages
        * [new branch]      issue/command-not-found -> algolia/issue/command-not-found
        * [new branch]      jekyll-v3  -> algolia/jekyll-v3
        * [new branch]      master     -> algolia/master
        * [new branch]      pr         -> algolia/pr
        * [new branch]      test/algolia-v1 -> algolia/test/algolia-v1
  4. Identify the branch you want to update. This is typically “master”.

  5. Checkout that branch:

    git checkout –track upstream/master

  6. Verify that branch:

    git status

  7. Review the changes:

    git ???

  8. Update gem dependencies:

    gem update

    The response:

    Updating installed gems

  9. Resolve conflicts, if any.

  10. Update dependencies:

    bundle install

  11. Make site changes public on GitHub later after configuration and testing.

Edit the repo so your own posts are indexed

You want your own content instead of the postings copied from the theme, right?

There are several customizations:

  1. Setup your own indexing service
  2. Configure _config.yml
  3. Specify Write API KEY
  4. Index in shell script

  5. Build index in CI

  6. Adjust theme colors and presentation
  7. Add new custom posts
  8. View refreshed site

  9. Erase sample posts

  10. Make site changes public on GitHub
  11. Replace site icon
  12. View Logs and Metrics

Setup your own indexing service

  1. Sign-up at Algolia.com (you can optionally use your GitHub credentials).

    A free account of up to 10,000 requests per day is available from Algolia.com.

    This video by Tim Carry (tim@algolia.com) illustrates his blog article:



  2. Specify the name and region where the majority of your visitors are located.

    Algoria’s UI has a cool list of live ping response times to various regions:



  3. Look at the email for links to their thorough demos and tutorials (doc), which populates your instance with example of actors.

Configure _config.yml

NOTE: Jekyll keeps its configuration information in a text file named _config.yml.

  1. Use a text editor to open the _config.yml file.

    Site title

  2. Manually change these values in the sample file:

    title:            Hyde
tagline:          'A Jekyll theme, with instant search'
description:      'The popular Hyde theme for Jekyll, now with instant-search capabilities. Made by @mdo and Algolia'

  3. Save the file and restart the server to see your changes on the website.

    Site URL

  4. Click Find and Replace from

    algolia/algoliasearch-jekyll-hyde

    to, for example:

    acme/acme.github.io

    would change these lines:

    url:              https://github.com/algolia/algoliasearch-jekyll-hyde
baseurl:          /algoliasearch-jekyll-hyde

    Site API KEY

  5. Switch to an internet browser with the Algolia Dashboard on your account.



    The value you see for application_id would be different that the example shown here.

  6. Copy the value of the Application ID by clicking on the icon to the right of each value or highlight each value and press Ctrl+C.

    NOTE: A Jekyll plugin (from Algolia or another) extracts every paragraph of text (between <p> and </p> tags) from HTML files generated by the jekyll build command. This approach of reading the final HTML pages instead of markdown text works with any markdown parser and custom plugin.

  7. Use a text editor to open the _config.yml file and paste in this under the gems: section:

    gems:
  - algoliasearch-jekyll

algolia:
  application_id: 'EILX55I5BP'
  index_name: 'jekyll_PROD'
  read_only_api_key: '6be0576ff61c053d5f9a3225e2a90f76'
  excluded_files:
    - 404.html
    - index.html

    application_id

  8. Highlight to value for application_id and paste yours to replace it.

    read_only_api

  9. As above, copy from the Dashboard the Search-Only API Key and replace the value of read_only_api_key in the _config.yml file.

    index_name

    NOTE: The Algolia plugin also adds metadata context to each paragraph before pushing the lot to the Algolia index in the cloud.

    PROTIP: Specify a different index name for PROD and TEST so you don’t mix different data.

  10. In _config.yml specify a index name such as “jekyll_PROD”.

  11. In _config-dev.yml specify a index name such as “jekyll_TEST”.

    NOTE: With Aloglia, an index does not need to be created manually ahead of index insertion.

  12. Save the file and restart the server to see your changes on the website. The response looks like this:

    Configuration file: /Users/mac/gits/jetbloom/jetbloom.github.io/_config.yml
 Indexing 822 items
Indexing of 822 items in jekyll_PROD done.

Create _algolia_api_key

PROTIP: Keep private from the world API keys with write permissons.

  1. Use a text editor to open file .gitignore file.

  2. Scroll to the bottom of the file to copy the _algolia_api_key entry.

    Functions in the Algolia JavaScript client library downloaded open a file with this name to retrieve the contents for use like a password associated with write and delete permissions.

  3. Close the file.

  4. Switch to an internet browser with the Algolia Dashboard on your account.

  5. Click the icon to the right of the Admin API Key value to copy it into your Clipboard.

    The key’s value is shown as dots in case someone else is looking over your shoulder.

  6. Switch back to the text editor to open a new file.
  7. Paste the API key in the file.
  8. Save the file in the repo folder as name _algolia_api_key (no file extension).
  9. Close the file.

Index in shell script

PROTIP: Combine several actions in the custom shell script, such as building the index.

  1. Use a text editor to edit the 4001.sh or 4001.cmd script created above to Run Jekyll locally.

  2. Identify the sub-modules installed:

    bundle exec jekyll -h

    The algolia sub-command should be listed.

  3. Replace the 4001 script file with this:

    
# build _site folder:
bundle exec jekyll build –config _config.yml,_config-dev.yml
# Index sub-command:
bundle exec jekyll algolia push
# Display:
bundle exec jekyll serve –config _config.yml,_config-dev.yml --port 4001

    This is constructed based on Jekyll documentation at https://jekyllrb.com/docs/usage/

    NOTE: The jekyll aloglia sub-command references the _algolia_api_key.

    Repeat your Ruby install and bundle install if you see this message:

    fatal: 'jekyll algolia' could not be found. You may need to install the jekyll-algolia gem or a related gem to be able to use this subcommand.

Update indexes in Continuous Integration

PROTIP: Update indexes using a continuous integration server set to automatically push data and reindex upon save.

There are several CI servers:

TODO: Add CI settings instructions.

  • Jenkins
  • Cloudbees SaaS running Jenkins
  • TravisCI
  • CircleCI

Adjust theme colors and presentation

Some themes pre-code alternative CSS that can be selected.

The Hyde theme at https://github.com/poole/hyde explains some changes in the format of the site’s layout. To change the color scheme of the site to green and flip the menu to the right side, change _layouts/default.html from:

<body class="theme-base-09">

to:

<body class="theme-base-0b layout-reverse">

The disadvantage of this convenience is that the CSS file can become “bloated”, and require longer to load by visitors.

Add new custom posts

NOTE: Content shown on Jekyll websites are defined as individual files within the _posts folder. This is a key differentiator of Jekyll vs. WordPress, Drupal, and others that store content in a database.

Files in the _posts folder can be moved among different Jekyll themes.

  1. Use a text editor to open an .md file within the _posts folder.

    Files names end with “.md” to designate markdown formatting. Jekyll processes such files into index.html files.

    There are other formats, such as

    Some text editors can provide text highlighting based on the file extension.

    The three dashes in the first line begins the “front matter” which Jekyll processes.

    ---
layout: post
title: Let's start the adventure
author:
  login: nicolas
  email: nicolas@algolia.com
  display_name: nicolas
  first_name: Nicolas
  last_name: Dessaigne
---

    NOTE: The post value in layout: post means that the post.html file in the _layouts folder is used to format text in the file.

  2. Replace the title and author.

    NOTE: Some other themes provide a default author so it doesn’t have to be entered on every post.

  3. Erase the remainder after the front matter (three dashes).
  4. Save the file with a different file name.
  5. View site again.

View refreshed site

  1. Switch to the Terminal window running Jekyll.

    Jekyll is set to detect changes to the file and re-generate HTML as needed.

    Regenerating: 1 file(s) changed at 2016-05-30 11:03:55 ...done in 5.612279 seconds.

  2. Switch to the internet browser and press Ctrl+R or click the icon to refresh the screen.

Erase sample posts

  1. Switch to the Finder on a Mac or File Explorer on Windows.
  2. Navigate to the _posts folder.
  3. Select all files in the folder except the one created above.
  4. Delete files selected.

Make site changes public on GitHub

PROTIP: Make a small change, then add and commit.

  1. If you use a command-line Git client:

    git add .
    git commit -m”Add sample posts”

  2. See if there is a remote local defined:

    git remote -v

  3. If there isn’t, define one (replacing the URL with yours):

    git remote add remote https://github.com/acme/acme.github.io

  4. Verify with another:

    git remote -v 

    origin http://github.com/acme/acme.github.io (fetch)
origin  http://github.com/acme/acme.github.io (push)

  5. Push commits to GitHub to verify the site running before customization.

    git push

  6. View your site using the public URL.

View Logs and Metrics

On the search service Dashboard:

NOTE: Alogia emails the number of calls each day.

Add search features to a base theme

NOTE: This section is not complete yet.

To add search features to another Jekyll theme, we dive into theme JavaScript, CSS, HTML, and configuration files.

PROTIP: The sequence in the video above shows a sequence of changes so you can make one change at a time and have it still working so you can verify each change.

  1. Get a copy of your custom theme working on your local machine
  2. Add a link to the algolia.css file in _includes/head.html
  3. Specify in .gitignore the file containing private keys
  4. Edit _config.yml to add your Algolia credentials
  5. Edit Gemfile (if you’re using bundler) to add the Jekyll Algolia plugin
  6. Edit _includes/footer.html to include the links to the needed JS files and templates
  7. Edit_includes/sidebar.html to add the search input
  8. Edit_layouts/default.html to replace the element where content is usually displayed and transform it into two elements. One for the “static” display (current blog post for example) and one for the “dynamic” display (search results). Only one of the two will be visible at a time, depending if the user is searching or reading public/css/search.css where you put all the search-specific styling (input, results, etc)
    • public/js/search.js where you put the search-specific javascript (instanciating the Algolia client, updating the render, etc)

Get a base theme working on your local machine.

My Jekyll Templates page lists several.

As an example, we’ll be modifying the Hyde theme since we’re already familiar with its look and feel.

PROTIP: We modify the theme so that we can test the effectiveness of each step.

  1. Open an internet browser to see the base theme demo:

    http://hyde.getpoole.com

  2. Click the link below to open the GitHub page for the theme:

    https://github.com/poole/hyde

    We will add a search box by adding additional HTML, CSS, configuration settings, and JavaScript programming.

  3. Click its Fork button to put it under your GitHub account.

  4. Click “Clone or download”, then Download Zip.

  5. Use Finder to open the “hyde-master.zip” in the Downloads folder.

  6. Unzip it.

  7. Move the folder to a directory such as “~/gits/jekyll”.

    NOTE: The folder does not contain a Gemfile.

  8. Navigate to that folder.

  9. Run Jekyll server to display the static site:

    jekyll serve

  10. Add a link to the algolia.css file in _includes/head.html

    <link rel="stylesheet" href="public/css/algolia.css">

    To check if this works, use your browser Debugger’s waterfall chart.

  11. Add CSS to style the search form and search results based on the contents within:

    https://github.com/algolia/algoliasearch-jekyll-hyde/blob/master/public/css/algolia.css

    What you actually add can be much different if you prefer to make use of SASS, etc.

    /* Search form */
.algolia__form {
  margin-bottom: 1rem;
}
 
.algolia__input {
  font-size: 20px;
  padding:.25rem .5rem;
}
 
/* Search results */
 
.algolia__initial-content {
  display:block;
}
.algolia__initial-content--hidden {
  display:none;
}
.algolia__search-content {
  display:none;
}
.algolia__search-content--active {
  display:block;
}
 
.algolia__result-link {
  font-size: 1.25rem;
  font-weight:bold;
}
.algolia__result-date {
  font-size:0.8rem;
}
.algolia__result-text {
}
.algolia__result-highlight {
  background: yellow;
  color:inherit;
}

    You won’t be able to check if this works until the form is added, below.

  12. Add the search form input field in the sidebar.html within _includes.

    Different templates use varying techniques to provide a form field for visitors to specify search terms.

    After saving, the form should appear. Adjust the CSS styling and positioning as you wish.

  13. Add the algolia.js library of JavaScript functions into the repo, such as the public/js folder.

    https://github.com/algolia/algoliasearch-jekyll-hyde/blob/master/public/js/algolia.js

  14. Add the HTML to display page titles and content in default.html within folder _layouts:

     <div class="content container">
   <div class="algolia__initial-content js-algolia__initial-content">\{\{ content \}\}</div>
  
   <div class="algolia__search-content js-algolia__search-content">
     <h1 class="page-title">Search</h1>
     <div class="posts algolia__results"></div>
   </div>
 </div>

  15. Add HTML links to the Algolia library within the HTTP footer.html within the _includes folder.

    <script>
  window.ALGOLIA_CONFIG = {
    'applicationId': 'EILX55I5BP',
    'indexName': 'your_index_name',
    'apiKey': ''
  }
</script>
<script id="algolia__template" type="text/template">
   
  <div class="algolia__result">
    <a class="algolia__result-link" href="{{ url }}#algolia:{{ css_selector }}">{{{ _highlightResult.title.value }}}</a>
    {{#posted_at}}
    <div class="algolia__result-date">{{ posted_at_readable }}</div>
    {{/posted_at}}
    <div class="algolia__result-text">{{{ _highlightResult.content.value }}}</div>
   
</script>
<script id="algolia__template--no-results" type="text/template">
  No results found.
</script>
<script src="//cdn.jsdelivr.net/jquery/2.1.4/jquery.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch/3.6.0/algoliasearch.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch.helper/2.1.0/algoliasearch.helper.min.js"></script>
<script src="//cdn.jsdelivr.net/hogan.js/3.0.2/hogan.min.js"></script>
<script src="//cdn.jsdelivr.net/momentjs/2.10.3/moment.min.js"></script>
<script src="public/js/algolia.js"></script>

  16. Adjust CDN.

    Although Algolia makes use of the jQuery library stored in a CDN, you can use another CDN (such as Google’s) if you prefer.

  17. Add dependencies and their versions in the Gemfile.lock file:

  18. Specify the Jekyll plugin in the Gemfile file:

    source 'https://rubygems.org'
 
gem 'jekyll', '>=2.5.3'
 
group :jekyll_plugins do
  gem 'algoliasearch-jekyll'
end

    .gitignore

  19. Edit the project’s .gitignore file so the key is not uploaded to GitHub:

    _algolia_api_key

    NOTE: The leading underline character tells Jekyll to not convert it into HTML.

  20. Edit variables and their values in the project’s _config.yml file.

### Replace Site Icon #

TODO: ReplaceSiteIcon

index.html

  1. Navigate down the folders to an index.html file and open it in a text editor.

    NOTE: All content files are named index.html so visitors don’t have to type in the .html file extension. It is better for SEO (Search Engine Optimization) if folder names are used as links.

    • Dashes are interpreted by search engines as spaces between words.
    • Underlines are interpreted as compound words.

  2. Press Ctrl+F to search for <article class="post"> a HTML5 standard tag to designate content (and not navigation and other fluff).

    Text in the file replaces the tag:

    {{ content }}

In the _includes folder of the Algolia template are the head.html, footer.html, and sidebar.html.

When a web page (index.html) is loaded by an internet browser at the client end, contents of the <head> are processed first.

The Algolia Jekyll theme defines that code in the head.html file.

That includes <link statements to bring in JavaScript and CSS files.

sidebar.html

The sidebar.html file contains what is within the <div class="sidebar"> tag positioned to the left of content on every page.

The search field is in that file:

<input type="text" class="algolia__input js-algolia__input"
autocomplete="off"
name="query"
placeholder="Search in this site..." />

TODO: Explain Notice there is no JavaScript “onClick” function here.

That’s because JavaScript functions have been invoked when the website was loaded to watch for changes in classes algolia__input and js-algolia__input.

footer.html

The footer.html file contains what goes before the </body> tag at the bottom of every page.

The Algoria template also defines JavaScript variables and populates them with values from the _config.xml file:

  <script>
  window.ALGOLIA_CONFIG = {
    'applicationId': '{{ site.algolia.application_id }}',
    'indexName': '{{ site.algolia.index_name }}',
    'apiKey': '{{ site.algolia.read_only_api_key }}',
    'baseurl': '{{ site.baseurl }}'
  }
</script>
<script id="algolia__template" type="text/template">
% raw %}
  <div class="algolia__result">
    <a class="algolia__result-link" href="{{ full_url }}#algolia:{{ css_selector }}">{{{ _highlightResult.title.value }}}</a>
    {{#posted_at}}
    <div class="algolia__result-date">{{ posted_at_readable }}</div>
    {{/posted_at}}
    <div class="algolia__result-text">{{{ _highlightResult.text.value }}}</div>
  </div>
% endraw %}
</script>
<script id="algolia__template--no-results" type="text/template">
  No results found.
</script>

JavaScript

The onLinkClick JavaScript function invoked is defined in the algolia.js file within the public/js folder.

  • onQueryChange

  • onResult

  • renderResults

  • getAnchorSelector

  • scrollPageToSelector

The above in turn reference functions in libraries pulled in from the internet:

<script src="//cdn.jsdelivr.net/jquery/2.1.4/jquery.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch/3.6.0/algoliasearch.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch.helper/2.1.0/algoliasearch.helper.min.js"></script>
<script src="//cdn.jsdelivr.net/hogan.js/3.0.2/hogan.min.js"></script>
<script src="//cdn.jsdelivr.net/momentjs/2.10.3/moment.min.js"></script>
<script src="/algoliasearch-jekyll-hyde/public/js/algolia.js"></script>

Search Field CSS Formatting

It seems there are as many ways to store CSS in Jekyll sites as there are Jekyll sites.

Each option involves changes to CSS as well to suit your design tastes.

The Algoria theme keeps CSS and JavaScript within a folder named public. A separate algoria.css file contains styling for both the search box and search results.

Notice it is raw CSS, with no SASS processing.

Many Jekyll templates use SASS, which expands style codes in sass files to generate CSS used in websites.

Additional resources about SASS:

The underline in the name means that the folder is not transferred into the _site folder.

Resources

  • Nick Zadrozny is the co-founder of Bonsai.io.

More on front-end styling

This is one of several topics:

  1. UI Design Systems
  2. Text Editors
  3. Markdown text for GitHub from HTML

  4. 508 Accessibility

  5. gRPC (g___ Remote Procedure Call)

  6. HTTP/2 Transition Project Plan

  7. Front-end UI creation options
  8. Docusaurus static website generator
  9. Static websites
  10. JAM Stack Website Project Plan
  11. Jekyll Site Development

  12. Gatsby app generator

  13. Website styles
  14. Website Styling

  15. VueJs front-end framework

  16. Protractor to automate testing of Angular and other web pages

  17. Email from website
  18. Search within Hyde format Jekyll websites

  19. Windows Tile Pin Picture to Website Feed

  20. Data Visualization using Tableau

Search within Hyde format Jekyll websites was published on .