見出しを翻訳するとページ内リンクが壊れる

[numb86]

現在、#で始まる見出しを翻訳すると、その見出しに対してリンクを張れなくなるという問題が発生しています。

例を上げると、このページの冒頭にある

アプリ内の関数コンポーネントの中で router オブジェクト へアクセスしたいときは、 useRouter フックを利用できます。以下の例をご覧ください:

の「router オブジェクト」というリンクを押下すると、同ページ内のこの見出しにジャンプすることが想定されているのですが、実際にはリンクを押下しても動作しません。

原因は、[`router` オブジェクト](#router-オブジェクト) というマークダウンを書くと、HTML 化する際に「オブジェクト」の部分がe382aae38396e382b8e382a7e382afe38388にエンコードされてしまうからです。
そのため、このリンクのhrefは#router-e392aae38396e382b8e382a7e382afe38388になり、そのような要素は存在せず、ジャンプが発生しないという状況になってしまっています。

この問題は日本語を含んでいる全ての見出しで発生することであり、何らかの対応が必要だと思います。

私が思い付く対策は、以下の 2 種類です。

1. aタグを使ってリンクを書く
2. Heading IDs を使う

aタグを使ってリンクを書く

[`router` オブジェクト](#router-オブジェクト)の代わりに<a href="#router-オブジェクト">`router` オブジェクト</a>のように書くことで、先程のエンコードの問題を回避できます。

Heading IDs を使う

Heading IDsはマークダウンの拡張構文で、

### router オブジェクト {#router-object}

というマークダウンが、

<h3 id="router-object">router オブジェクト</h3>

という HTML に変換されます。

この構文を利用することで、アンカー名を英語のままにすることができるので、aタグを使わなくてもこの見出しにリンクを張ることができます。

現状ではこの構文はサポートされていませんが、ローカル環境で試したところ、以下のプラグインを使うことで導入できました。
imcuttle/remark-heading-id: The remark plugin for supporting custom heading id

どちらを使うべきか

Heading IDs が望ましいと考えています。

マークダウンファイルのなかにaタグを書くのが不格好で煩雑、というのもあるのですが、見出しからアンカー名を自動生成していること自体が望ましくないと考えています。

今の仕組みだと、見出しを翻訳する度にアンカー名が変わってしまうため、そこに対するリンクも修正する必要があります。これは手間ですし、見落とす可能性が十分にあります。
現に、このページにも「router オブジェクト」へのリンクがあるのですが、翻訳に合わせた対応は行われておらず、#router-objectへのリンクになっています。このようなアンカーは存在しないので当然、ワークしていません。
Heading IDs を使ってアンカー名を原文と同じにするようにすれば、[`router` オブジェクト](#router-object)を[`router` オブジェクト](#router-オブジェクト)を書き換えるような作業は発生しません。

また、アンカー名は URL の一部なので、日本語を含めるべきではないと思います。
オリジン以降のパスは、本家と翻訳ドキュメントとで一致しているのが分かりやすくて望ましいと思いますが、アンカー名が翻訳されてしまうと、その関係が崩れてしまいます。
このような観点からも、Heading IDs を導入して「見出しのテキスト」と「アンカー名」を切り離すべきだと考えます。

もちろん、より望ましい解決策、よりシンプルな解決策があれば、それに越したことはないのですが。