xref links don't always jump to definition

[agoose77]

I've noticed that certain XRefs do not jump to the HTML node that contains their definition.

After some debugging, it seems that it's a myst-theme bug. For example:

See [](xref:guide#setting:myst_to_tex:beamer) and <xref:guide#admonitions-list> and <xref:guide#term-index>

The final xref doesn't generate a link with an anchor.

I determined that this is a frontend problem by inspecting the underlying xref data, and the final page AST; the final XRef is missing an html_id:

Details

{
  "kind": "Article",
  "sha256": "e0fcdf1c04b9ec7419d7e7ba3875bc9b3ddde5d23124a78f1211f1299eb4b4b7",
  "slug": "index",
  "location": "/index.md",
  "dependencies": [],
  "frontmatter": {
    "title": "Index",
    "content_includes_title": false,
    "exports": [
      {
        "format": "md",
        "filename": "index.md",
        "url": "http://localhost:3101/index-cc27c46580ed59b99a2712a0c879c38f.md"
      }
    ]
  },
  "mdast": {
    "type": "root",
    "children": [
      {
        "type": "block",
        "children": [
          {
            "type": "paragraph",
            "position": {
              "start": {
                "line": 3,
                "column": 1
              },
              "end": {
                "line": 3,
                "column": 1
              }
            },
            "children": [
              {
                "type": "text",
                "value": "See ",
                "position": {
                  "start": {
                    "line": 3,
                    "column": 1
                  },
                  "end": {
                    "line": 3,
                    "column": 1
                  }
                },
                "key": "fXD7STkl8o"
              },
              {
                "type": "crossReference",
                "url": "/settings",
                "position": {
                  "start": {
                    "line": 3,
                    "column": 1
                  },
                  "end": {
                    "line": 3,
                    "column": 1
                  }
                },
                "children": [
                  {
                    "type": "text",
                    "value": "beamer",
                    "position": {
                      "start": {
                        "line": 50,
                        "column": 1
                      },
                      "end": {
                        "line": 50,
                        "column": 1
                      }
                    },
                    "key": "IGuGpOkSGu"
                  }
                ],
                "urlSource": "xref:guide#setting:myst_to_tex:beamer",
                "remote": true,
                "remoteBaseUrl": "https://mystmd.org/guide",
                "dataUrl": "/settings.json",
                "identifier": "setting:myst_to_tex:beamer",
                "label": "setting:myst_to_tex:beamer",
                "html_id": "setting-myst-to-tex-beamer",
                "protocol": "xref:myst",
                "template": "{name}",
                "resolved": true,
                "key": "TALXOffZBf"
              },
              {
                "type": "text",
                "value": " and ",
                "position": {
                  "start": {
                    "line": 3,
                    "column": 1
                  },
                  "end": {
                    "line": 3,
                    "column": 1
                  }
                },
                "key": "e90BMZW85n"
              },
              {
                "type": "crossReference",
                "url": "/admonitions",
                "position": {
                  "start": {
                    "line": 3,
                    "column": 1
                  },
                  "end": {
                    "line": 3,
                    "column": 1
                  }
                },
                "children": [
                  {
                    "type": "text",
                    "value": "Table ",
                    "key": "CJ4PVekbgT"
                  },
                  {
                    "type": "text",
                    "value": "1",
                    "key": "kfTbmvVXqI"
                  }
                ],
                "urlSource": "xref:guide#admonitions-list",
                "remote": true,
                "remoteBaseUrl": "https://mystmd.org/guide",
                "dataUrl": "/admonitions.json",
                "identifier": "admonitions-list",
                "label": "admonitions-list",
                "html_id": "admonitions-list",
                "protocol": "xref:myst",
                "template": "Table %s",
                "enumerator": "1",
                "resolved": true,
                "key": "j1vVyk3rhF"
              },
              {
                "type": "text",
                "value": " and ",
                "position": {
                  "start": {
                    "line": 3,
                    "column": 1
                  },
                  "end": {
                    "line": 3,
                    "column": 1
                  }
                },
                "key": "vSk4IQ4ftP"
              },
              {
                "type": "crossReference",
                "url": "/glossaries-and-terms",
                "position": {
                  "start": {
                    "line": 3,
                    "column": 1
                  },
                  "end": {
                    "line": 3,
                    "column": 1
                  }
                },
                "children": [
                  {
                    "type": "text",
                    "value": "index",
                    "position": {
                      "start": {
                        "line": 27,
                        "column": 1
                      },
                      "end": {
                        "line": 27,
                        "column": 1
                      }
                    },
                    "key": "gAMsE644g1"
                  }
                ],
                "urlSource": "xref:guide#term-index",
                "remote": true,
                "remoteBaseUrl": "https://mystmd.org/guide",
                "dataUrl": "/glossaries-and-terms.json",
                "identifier": "term-index",
                "label": "term-index",
                "protocol": "xref:myst",
                "template": "{name}",
                "resolved": true,
                "key": "OfsJghVMy6"
              }
            ],
            "key": "QQ2wwosInw"
          }
        ],
        "key": "JuLtpwPX5o"
      }
    ],
    "key": "F4r1nKeNHc"
  },
  "references": {
    "cite": {
      "order": [],
      "data": {}
    }
  },
  "footer": {
    "navigation": {}
  },
  "domain": "http://localhost:3001"
}

By inspecting the React renderer for crossReference, it looks like we don't have a fall-back for cases without html_id:

myst-theme/packages/myst-to-react/src/crossReference.tsx

Line 180 in 815265f

href={`${createRemoteBaseUrl(url, remoteBaseUrl)}${htmlId ? `#${htmlId}` : ''}`}

I don't know enough about the assumptions here to suggest the proper fix. Is html_id in the AST supposed to be an escaped form of identifier, present only if necessary? If so, then myst-theme should use html_id ?? identifier. Otherwise, is it possible for a node to have identifier but that identifier be absent in the DOM?

Pinging @rowanc1 for guidance, but this is not urgent.