• HOME
  • USER GUIDE
  • SHOWCASE
  • ABOUT
  • User Guide → Making the Site Searchable

    Making the Site Searchable

    MarkBind comes with with an in-built site search facility with the option to use third-party search services as well.

    All markdown and html headings of levels 1-3 are captured in the search index by default. You can change this setting using the headingIndexLevel property of the site.json.

    If you do not wish to use MarkBind's searchbar (e.g. you have an external service provider), it may be helpful to include the option enableSearch: false in your site.json. This stops MarkBind from indexing search headings and speeds up building.

    Search Bars

    You can add a search bar component to your website to allow users to search the site.

    CODE:

    <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
    <searchbar :data="searchData" placeholder="Search (Right-aligned dropdown)" :on-hit="searchCallback" menu-align-right></searchbar>
    

    To use the searchbar within a navbar, add the following markup to your file. The searchbar can be positioned using the slot attribute for the list. The following markup adds a searchbar to the right side of the navbar with appropriate styling.

    <li slot="right">
      <form class="navbar-form">
        <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
      </form>
    </li>
    

    OUTPUT:

    Enter a search term (eg. 'search bar') to see the search result dropdown.

    Options

    Name Type Default Description
    algolia Boolean false Whether the searchbar should be connected to Algolia DocSearch.
    data Array The local data source for suggestions. Expected to be a primitive array. To use MarkBind's search functionality, set this value to "searchData".
    menu-align-right Boolean false Whether the search bar's dropdown list will be right-aligned.
    on-hit Function A callback function when you click or hit return on an item. To use MarkBind's search functionality, set this value to "searchCallback".
    placeholder String '' The placeholder text shown when no keywords are entered in the search bar.

    Note: If you are using MarkBind's search functionality, then enableSearch must be set to true in site.json.

    See: User Guide: Site Configuration → enableSearch.

    Related topic: User Guide: Making the Site Searchable.

    Related topic: User Guide: Using Plugins → Algolia: Enabling Algolia DocSearch.

    Keywords

    regress regression testing

    You can also specify additional keywords to be indexed under a heading by tagging the words with the keyword class. Those keywords will be linked to the heading immediately above it. If you want to index a keyword without rendering it in the page, add d-none as a class.

    Example

    #### Developer Testing
    <span class="keyword d-none">regress</span>
    <span class="keyword d-none">regression testing</span>
    
    This is good for catching <span class="keyword">regressions</span>.
    

    Developer Testing

    This is good for catching regressions.

    You can also set additional keywords to be indexed for an entire page using the keywords attribute inside the <frontmatter> of that page.

    Example

    <frontmatter>
      keywords: regress, regression testing, regressions
    </frontmatter>
    ...
    
    <span class="keyword d-none">regress</span>
    

    Including or Excluding Headings

    You can specify headings which are to be included or excluded from the index built by MarkBind's built-in search feature using the .always-index or .no-index classes.

    If you wish to index a specific heading outside the specified headingIndexLevel, you may add the .always-index attribute to the heading. Similarly, if you wish for a specific heading inside the specified headingIndexLevel not to be indexed, you may add the .no-index attribute to the heading.

    Example

    ###### Heading outside heading index level that will be indexed {.always-index}
    
    # Heading inside heading index level that will not be indexed {.no-index}
    

    Equivalently,

    <h6 class="always-index"> Heading outside heading index level that will be indexed </h6>
    
    <h1 class="no-index"> Heading inside heading index level that will not be indexed </h1>
    

    Using External Search Services

    MarkBind sites can use Algolia Doc Search services easily via the Algolia plugin. Unlike the built-in search, Algolia provides full-text search. See the panel below for more info.

    Plugin: Algolia

    This plugin allows you to use Algolia DocSearch for your site.

    To enable it, add algolia to your site's plugins, and supply the required options via the pluginsContext.

    Name Type Default Description
    apiKey String The API key for your site's Algolia DocSearch setup
    indexName String The index name for your site's Algolia DocSearch setup
    algoliaOptions Object {} A JSON object specifying additional options for DocSearch
    debug Boolean false Whether to turn on debug mode to allow inspection of CSS styles for the dropdown
    site.json
    {
      ...
      "plugins": [
        "algolia"
      ],
      "pluginsContext": {
        "algolia": {
          "apiKey": "25626fae796133dc1e734c6bcaaeac3c", // replace with your site's api key
          "indexName": "docsearch", // replace with your site's index name
          "algoliaOptions": { "hitsPerPage": 10 }, // optional
          "debug": false // optional
        }
      }
    }
    

    To connect the searchbar component to Algolia DocSearch, add the algolia key.

    <searchbar placeholder="Search" algolia menu-align-right></searchbar>
    

    Alternatively, if you are using a custom search bar, you can assign the input field the id algolia-search-input to connect it to Algolia DocSearch.

    <input id="algolia-search-input">
    

    By default, Algolia DocSearch indexes all content on the page, including content in components that are hidden to the user during the initial render (e.g. Panels). To exclude these content from being indexed, you can add .algolia-no-index to the selectors_exclude attribute in your DocSearch configuration.

    The algolia-no-index class is automatically added to content hidden by MarkBind's Vue components. You may also add the algolia-no-index class to content that you do not want to be indexed by Algolia DocSearch.