doc: Improve docs search engine indexing

[josherich]

There's no way to access api from search engine in one click.

It's very hard to search node api from search engine. A typical example would be searching node writefilesync, the top result points to https://nodejs.org/api/fs.html without the heading hash #fs_fs_writefilesync_file_data_options.

In most cases, it's sth like the following, where there's a jump to xxx link to the hashed url https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Body

I'm not sure what's missing here, a quick search seems to suggest search engine need a unique id in headings like <h4 id="xxx"></h4> to tell the heading structure.

Since there's no search bar in the doc, it seems using search engine followed by Ctrl+F is the only way to find an api.

[Trott]

/ping @nodejs/website for suggestions

[cjihrig]

I'm just guessing here, but could the problem be that all of our link targets are just #? See the example below from the docs (with spacing added for readability):

<h2>
  <code>fs.writeFileSync(file, data[, options])</code>
  <span>
    <a class="mark" href="#fs_fs_writefilesync_file_data_options" 
       id="fs_fs_writefilesync_file_data_options">#</a>
  </span>
</h2>

[XhmikosR]

I'd also guess it's because there are no IDs in headings. But we need to find some docs about this so that we are sure before making any changes.

Try using https://khan.github.io/tota11y/ and see how the headings are just identified as header-name# while in the MDN page they have proper IDs.

BTW another issue is with the anchors; their name is not descriptive, but this has to do with accessibility

[josherich]

(could be outdated) According to using-named-anchors-to-identify

There are a few things you can do to increase the chances that they might appear on your pages. First, ensure that long, multi-topic pages on your site are well-structured and broken into distinct logical sections. Second, ensure that each section has an associated anchor with a descriptive name (i.e., not just "Section 2.1"), and that your page includes a "table of contents" which links to the individual anchors.

there's no exact rules to follow, a TOC and anchors should be sufficient. Most likely, id=xxx on h tag is considered more "well-structured".