Как создать идентификаторы привязки для списков определений (помеченных) в AsciiDo c или reStructuredText?

Question

Я пишу документацию на GitHub и хотел бы сделать ссылки на хэштеги на отдельные термины в моих списках определений (списки, помеченные AKA, списки описаний). Пример: https://github.com/username/projectname/wiki/SomeArticle#my-term

Kramdown предоставляет удобную функцию , которая генерирует идентификаторы элементов для всех терминов в списке определений. Однако Kramdown нельзя использовать в качестве средства рендеринга в вики-сайте GitHub.

Существует ли аналогичная функция для AsciiDo c или reStructuredText? Насколько я знаю:

• AsciiDo c позволяет определять пользовательские привязки . Но я не хочу добавлять привязки вручную, если это возможно.
• (на основе sphinx) reStructuredText поддерживает создание и привязку к пользовательским меткам , но, похоже, это не работает на GitHub.
• reStructuredText позволяет вам ссылаться на любой термин в глоссарии , используя роль :term:. Однако GitHub также не поддерживает директиву .. glossary::.

Если не считать отход от GitHub wiki (что для меня плохо), что я могу сделать?

Answer 1

Для Asciidoctor вы можете добавить идентификатор к каждому термину в списке определений:

[[apple]]Apple::
  A red fruit

[[banana]]Banana::
  A yellow fruit

Затем вы можете связать их с синтаксисом перекрестных ссылок на странице:

See <<apple>> for more details.

Как видите, разметка довольно проста. Если вы не хотите добавлять идентификатор вручную, вы можете написать скрипт для его добавления. Например, если у вас есть документ вроде:

= Document

Apple::
  A red fruit.

Banana::
  A yellow fruit.

Вы можете сделать это:

cat file.adoc | perl -ne 's/^([^:\[]+)::$/[[\L$1\E]]$1::/; print $_'

, который печатает:

= Document

[[apple]]Apple::
  A red fruit.

[[banana]]Banana::
  A yellow fruit.

Если вам нужно сохранить в результате сделайте следующее:

cat file.adoc | perl -ne 's/^([^:\[]+)::$/[[\L$1\E]]$1::/; print $_' > file_with_id.adoc

Примечание. Если ваш список определений содержит термины с пробелами, вам потребуется проделать дополнительную работу, чтобы преобразовать пробелы в дефисы или другие HTML безопасные символы идентификатора.