Skip to content

doc: Improve docs search engine indexing #31598

Closed as not planned
Closed as not planned
doc: Improve docs search engine indexing#31598
Labels
docIssues and PRs related to Node.js documentation.metaIssues and PRs related to the general management of the project.staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.

Description

@josherich
josherich
opened on Feb 1, 2020

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.

image

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

Screen Shot 2020-01-30 at 2 40 14 PM

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.

Activity

  1. Trott commented on Feb 1, 2020

    @Trott
    Trott
    on Feb 1, 2020
    Member

    /ping @nodejs/website for suggestions

  2. cjihrig commented on Feb 1, 2020

    @cjihrig
    cjihrig
    on Feb 1, 2020
    Contributor

    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>

  3. XhmikosR commented on Feb 1, 2020

    @XhmikosR
    XhmikosR
    on Feb 1, 2020
    Contributor

    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

  4. josherich commented on Feb 10, 2020

    @josherich
    josherich
    on Feb 10, 2020
    Author

    (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".

  5. targos
    added
    docIssues and PRs related to Node.js documentation.
    on Dec 26, 2020
  6. targos
    added
    metaIssues and PRs related to the general management of the project.
    on Aug 9, 2021

  7. github-actions commented on Jun 27, 2026

    @github-actions
    github-actionsbot
    on Jun 27, 2026 – with GitHub Actions
    Contributor

    This issue has been marked as stale due to 210 days of inactivity.
    It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

  8. github-actions
    added
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on Jun 27, 2026
  9. avivkeller
    linked a pull request that will close this issuebuild, doc: move to redesign #62045on Jul 14, 2026

  10. github-actions commented on Jul 28, 2026

    @github-actions
    github-actionsbot
    on Jul 28, 2026 – with GitHub Actions
    Contributor

    This issue has been automatically closed after 30 days of inactivity following its stale status (no activity for a total of 120 days).
    If this is still relevant, feel free to reopen it or leave a comment with additional details so we can continue the discussion.

  11. github-actions
    closed this as not plannedon Jul 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docIssues and PRs related to Node.js documentation.metaIssues and PRs related to the general management of the project.staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions