Missing anchors when searching

[benruijl]

When searching for a method, the search result does not contain the anchor to the method description, so the searcher is routed to the top of the relevant page. For example the following method:

has an anchor reference/Expression.html#symbolica.Expression.apart. When searching this anchor is missing:

Note that the second hit has the anchor #methods.

[machow]

Thanks for exploring this--what level is the apart header? It looks like the searchbar is flagging the Expression section. I wonder if lower level headers (e.g. h3+) tend to be passed over in the search.

I don't know how much we'll be able to do, but it seems important for how we end up recommending people structure docs (since search is super common for finding things 😓 ).

[benruijl]

It's h3 indeed:

### apart { #symbolica.Expression.apart }

and the methods section is h2:

## Methods

| Name | Description |
| --- | --- |
| [apart](#symbolica.Expression.apart) | Compute the partial fraction decomposition in `x`. |

[machow]

Ok, thanks -- this is helpful! Looking at the quarto docs on search, I'm not sure exactly how search works, but can explore a bit. One option for customizing could be using algolia (mentioned in the docs).

@cscheid, any chance there might be some helpful rules of thumb for understanding search in quarto? For example, are h3 headings too deep to be linked to in search?

[cscheid]

We definitely need to, except that I don't actually understand the limitations myself. It'll be a side quest for us, so no immediate promises on the turnaround time..

[benruijl]

To improve the search, I manually do the following changes:

# Transformer { #symbolica.Transformer }

`Transformer()`

Operations that transform an expression.

## Methods

| Name | Description |
| --- | --- |
| [chain](#symbolica.Transformer.chain) | Chain several transformers. `chain(A,B,C)` is the same as `A.B.C`, |

### chain { #symbolica.Transformer.chain }

`Transformer.chain(*transformers)`

Chain several transformers. `chain(A,B,C)` is the same as `A.B.C`,
where `A`, `B`, `C` are transformers.

#### Examples

into:

---
title: Transformer
---

`Transformer()`

Operations that transform an expression.

### Methods

| Name | Description |
| --- | --- |
| [chain](#symbolica.Transformer.chain) | Chain several transformers. `chain(A,B,C)` is the same as `A.B.C`, |

## chain { #symbolica.Transformer.chain }

`Transformer.chain(*transformers)`

Chain several transformers. `chain(A,B,C)` is the same as `A.B.C`,
where `A`, `B`, `C` are transformers.

#### Examples

So essentially I exchange h2 and h3 and remove the h1 (I don't know how to reintroduce the {symbolica.Transformer}). I now get:

The changes make sure that the indexer finds the actual method definition itself and removing the # and changing it into a tile makes sure that the breadcrumbs work, and it prevents the creation of a giant body of text in the search.json that trips up the Algolia search backend.