Prep for Bootstrap 4.1

[mdo]

When we release v4.1 in the coming weeks (possibly next week, likely week after), we'll have a new docs subfolder to point to. We'll still have the v4.0 docs at the existing URLs though and will link to those through our site's header.

I'm unsure what else needs modifying here, but we'll need a fresh index of the new docs I imagine.

[s-pace]

👋 @mdo,

You are right, better safe than sorry.

You can also use the same index and only add some variables like:

{
 "index_name": "bootstrap-v4",
"start_urls": [
    {
      "url": "https://getbootstrap.com/docs/(?P<version>.*?)/",
      "variables": {
         "version": [
           "4.0",
           "4.1"
         ]
       }
    }
 ]
[...]
}

This variable will also behave as attributeForFaceting which means than you can filter results by version
You will only need from your JS snippet and add the following input:

algoliaOptions: { 'facetFilters': ["version:4.1"] },

Let me know what do you think about that.

Cheers

[s-pace]

Reminder @mdo

[mdo]

Hey @s-pace! Sorry for the radio silence here for the last few weeks. We just shipped v4.1 (we have https://getbootstrap.com/docs/4.1/ and https://getbootstrap.com/docs/4.0/ now) and I forgot to check in here to see what else I had to do to update our docsearch setup. Can you confirm that I should only make some changes to filter by version, or should it be a new index? Is there anything I can do to kick off a new index?

Thanks!

[s-pace]

Sure thing:

Let's use this index for testing purposes and we will populate it into bootstrap-v4

Congratulations, your search is now ready!
I've successfully configured the underlying crawler and it will now run every 24h.

You're now a few steps away from having it working on your website:

• Copy the following CSS/JS snippets and add them to your page

<!-- at the end of the HEAD --> 
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" /> 

<!-- at the end of the BODY --> 
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script> 
<script type="text/javascript"> docsearch({ 
 apiKey: '7010a93e8b7e97e40e5cadfbaa9e9f04', 
 indexName: 'bootstrap-v4_temp', 
 inputSelector: '### REPLACE ME ####', 
 algoliaOptions: { 'facetFilters': ["version:$VERSION"] }, 
 debug: false // Set debug to true if you want to inspect the dropdown 
}); 
</script> 

• Add a search input in your page if you don't have any yet. Then update the inputSelector value in JS snippet to a CSS selector that targets your search input field.

• Replace $VERSION with the version you want to search on.
    The list of possible version is hardcoded in the config.
    So as of today you have: 4.0, 4.1

 For example if you want to refine the search to the version "4.0" just specify:

'facetFilters': ["version:4.0"] 

• Optionally customize the look and feel by following the DocSearch documentation
• You can also check your configuration in our github repo.

Feel free to get back to us if you have any issues or questions regarding the integration.

We'd also be happy to get your feedback and thoughts about DocSearch - so we can continue to improve it.

Have a nice day :)

[XhmikosR]

Thanks for the reply @s-pace.

I had already made twbs/bootstrap#26247. I tested just now with the test index and works as expected.

Now, the thing is, we have old content which can be tricky to rebuild.

Can we use a new index for 4.1.0 and on, with the version solution? This way the old search would still work and we'll just need to update our latest release's docs only.

[s-pace]

👋 @XhmikosR ,

It looks like twbs/bootstrap#26247 was enough. bootstrap-v4 is updated every 24h.

Anyway, I have made you a new index bootstrap cf 0740314

<!-- at the end of the HEAD -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />

<!-- at the end of the BODY -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
  apiKey: '### REPLACE ME ####',
  indexName: 'bootstrap',
  inputSelector: '### REPLACE ME ####',
  algoliaOptions: { 'facetFilters': ["version:$VERSION"] },
  debug: false // Set debug to true if you want to inspect the dropdown
});
</script>

[XhmikosR]

Thanks, @s-pace.

I'll switch to that after I discuss the timing with @mdo.

[s-pace]

👋 @XhmikosR ,

Let us know if you need any help :)

Have a nice week end

[XhmikosR]

I haven't heard from @mdo yet, @s-pace .

[mdo]

@XhmikosR @s-pace Hey y'all! Back from a weekend trip. Sounds like we're updating the docs index, or do we just need to rebuild the new 4.1 docs, @XhmikosR?

[s-pace]

👋 If you want to update the index, it will be made within 24h. Otherwise I can trigger it for you before the release.

Everything is ready on our side. Hope you will manage to be ready too :)

Break a leg

[XhmikosR]

@mdo twbs/bootstrap#26247 (comment)

[s-pace]

Closing it, feel free to reopen if required

[XhmikosR]

Hey, @s-pace!

So, we are about to release 3.4.0. We are using the config where we pass the docs version in facetFilters. What needs to be done to make this work for 3.4 too before we make the release?

[XhmikosR]

Friendly ping @s-pace @maxiloc since we want to release this soon :)

[s-pace]

👋 @XhmikosR ,

Sorry for the delay,

In order to avoid any confusion here, does the your 3.4 pages will keep the same layout than the https://getbootstrap.com/docs/4.1/* ones ?

  "selectors": {
    "lvl0": {
      "selector": ".bd-toc-item.active > a",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": ".bd-content h1",
    "lvl2": ".bd-content h2",
    "lvl3": ".bd-content h3",
    "lvl4": ".bd-content h4",
    "lvl5": ".bd-content h5",
    "text": ".bd-content p, .bd-content li, .bd-example"
  },

If these selectors can be used, we will only update the configuration we want you to use

We would like to avoid having multiple DocSearch indices to make it easier.

---

Pages https://getbootstrap.com/docs/4.0/ can now be updated with the bootstrap index instead of bootstrap-v4

indexName: 'bootstrap',
apiKey: '5990ad008512000bba2cf951ccf0332f'
algoliaOptions: { 'facetFilters': ["version:$VERSION"] },

Replace $VERSION with the version you want to search on. The list of possible version is hardcoded in the config. So as of today you have: 4.0, 4.1. (You can tried it out, it is live)

For example if you want to refine the search to the version "4.0" just specify: 'facetFilters': ["version:4.0"].

3.4 will be added as soon as pages https://getbootstrap.com/docs/3.4/ will be available and crawled (within 24h).

Please ping us as soon as these pages are available and let us know if you have any other question / pain point.

[XhmikosR]

@s-pace: I don't think we will touch 4.0, so please keep that index. It's not updated so maybe we will do the switch to later.

/3.4/ is using the same search code adapted twbs/bootstrap@515119b, but it doesn't use the same layout as 4.x.

[s-pace]

Alright @XhmikosR

Do you have an available version of your 3.4 pages (e.g. netlify)? I would like to tailor the selectors.

Otherwise we could use the same as the old index

[XhmikosR]

The selectors should be the same, yeah.

Only thing I'd change is switch to https. We will eventually enforce this. (I know we are already late :/)

[s-pace]

Alright, do you have any temporary version available? I would like to test a crawl first. Otherwise we will provide you a dedicated DocSearch index for this version

[XhmikosR]

Try this one https://epic-goldstine-3a9d25.netlify.com/

[s-pace]

Alright, please submit a PR of the newest configuration with the final URLs.

Ping us as soon as the new version is live, we will merge and deploy it asap.

The credential to use for this version would be:

apiKey: 'c8948afa20e6437a6e829f7e87b9ac11',
indexName: 'bootstrap-v3'

You can already give it a try with the staging environment.

Feel free to apply with the email addresses you want us to invite in order to provide you the algolia analytics we provide for your indices.

[XhmikosR]

@s-pace: so, we don't need to pass facetFilters for this?

I was under the impression that we pass the version so that we can use the same index?

[s-pace]

@XhmikosR you do not need to pass this parameter since we have created a new index for this version.

We would rather use the same index for every versions but since you want to keep one dedicated index for the v4, we will wait for you to be ready and merge them later on.

[XhmikosR]

@s-pace: ah, makes sense now, thanks.

One last thing. Is the bootstrap-v3 index supposed to work yet? I'm trying to see how styles will look locally.

[s-pace]

@XhmikosR you are welcome,

This index is now working but populated with your staging website. You will need to submit a PR on this repo in order to update the URL. We will merge and deploy it as soon as your production will be live.

Let us know if you want to change anything.

[XhmikosR]

The thing is that it doesn't work for me locally unless I pass the version, which contradicts with what you said above :)

So, using c8948afa20e6437a6e829f7e87b9ac11, bootstrap-v3 and passing 3.4 does show the netlify results, without having any facetFilters code. Which is weird... Without data-docs-version in the HTML I can't get the search window to even show; it's just set as display:none.

[XhmikosR]

Ah, nvm it's our problem :)

[XhmikosR]

@s-pace: I think 3.4 is wrong here https://github.com/algolia/docsearch-configs/blob/master/configs/bootstrap.json#L8 since the selectors we have there won't be present in 3.4.

[s-pace]

@XhmikosR please use these two credentials for the v3.4:

apiKey: 'c8948afa20e6437a6e829f7e87b9ac11',
indexName: 'bootstrap-v3'

You will only have the version 3.4 stored in this index bootstrap-v3.

We will only use the bootstrap index for versions superior to 4.1

I have removed the confusing version that was set before you told us you do not want to use one index only.