銀の弾丸

プログラミングに関して、いろいろ書き残していければと思っております。

AsciiDocで文書内の任意の場所にリンクする

f:id:takamints:20200627135648j:plain
photo credit: verchmarco Open book with a cone symbolising the snug time of the year staying inside and reading via photopin (license)

正式な文書はAsciidocで書いてPDFを出力することが多くなっています。 しかし、いつでもAsciidocを書いているわけでもありません。コードも書かなきゃならんし、メモ書き程度ならマークダウンで充分だし。

「さあ今日はガッツリ設計書を書きますよ~」って時に、あれ?リンクを貼るのってどうするんだっけ?といったことがよくあります。というか毎回そうなっている。ぼんやりとは覚えているけれど、正しくレンダリングされないとか。

こんな時は、すぐに検索するのですが、Asciidocの書き方を説明してくれてるページって、「見出しはこうする。テーブルはこう書けば良い・・・」みたいな感じが多くて、いろんな記法の説明がたくさん詰まっているもんで、いま知りたいことが、すぐわからない。

しかし文句ばっかり言ってちゃダメです。無いなら自分で書いときましょう。一旦書いたら割と覚えておけたりするもんで・・・。

てなことで、ここでは「文書内の任意の場所に飛べるリンクの書き方」を書いています。 外部の文書や、見出しへの自動リンクについてはまた別の機会に。

目次

概要

AsciiDocで、文書内の任意の場所にリンクを貼るには、 リンク先に「アンカーID」を設定し、 リンク元では「アンカーID」と「リンクテキスト」を指定します。

リンク先に アンカーID を設定する

リンク先に アンカーID を設定するには、その直前の行の行頭から、 [[アンカーID]] と記述します。

[[anchor-id]]
この段落がリンク先です。この直前に anchor-id が設定されています。

文書内へのリンクを記述

AsciiDocで、文書内の任意の場所にリンクを貼るには、 「<<アンカーID,リンクテキスト>>」 と記述します 。

リンクを貼るには、<<anchor-id,このように>> 記述します。

アンカーID は、 リンク先に設定しておく識別子です(「アンカー(anchor)」はイカリの意味)。 日本語でも構わないようですが、 私はなるべく英数字+ハイフンなどを使っています。 検索する時に便利なので。

文書内リンクの例

リンクを貼るには、<<anchor-id,このように>> 記述します。


[[anchor-id]]
リンク先の文章です。

アンカーID は、文書内で複数同じものが設定されていてはいけません。 複数あると、どこにリンクすればよいかわかりませんから。