Ссылки в Confluence. Mazafaka

Автор: | 25.11.2015

Confluence 5.5.2 — прекрасная SaaS-система, пользуюсь ежедневно. Полностью интегрируется с Jira, все дела.

В Confluence можно грамотно разметить оглавления в тексте, заголовками уровня 1-6.

Можно вставить автоматически собираемое «Содержание» всех заголовков на странице (макрос ‘Table of Contents’).

Можно вставлять в тело страницы другую страницу, целиком (макрос ‘Include Page’).

Даже можно сделать на странице, содержимое которой надо встроить, специальное выделение текста (макрос ‘Excerpt’), и вставлять ТОЛЬКО то содержимое, которое было помеченное таким хитрым образом (макрос ‘Excerpt Include’).

Можно вставлять ссылки на другие страницы внутри Confluence аж двумя способами: по-простому (по-дурацки) и грамотно.

Вставляем по-дурацки

  1. Просто скопируй нужную ссылку из адресной строки, да вставь ее в нужное место на странице открытым текстом.

Буквально copy/paste ‘httр://confluence.test/display/~a.lupan/Action+Verbs+to+be+used+in+Goal+setting+process‘ в тело открытой на редактирование страницы.

Сработает сразу.

Но вероятно не будет работать в будущем, если в названии страницы изменится хотя бы один символ — ссылка просто «умрёт».

Например, если в названии только дружественные англо-символы (вроде «Action Verbs to be used in Goal setting process«), URL страницы будет выглядеть как ‘httр://confluence.test/display/~a.lupan/Action+Verbs+to+be+used+in+Goal+setting+process

Если изменить заголовок страницы на «Англ Action Verbs to be used in Goal setting process» (добавить неанглоалфавитный символ, или двоеточия, или что-то еще неординарное), URL страницы поменяется на что-то вроде ‘httр://confluence.test/pages/viewpage.action?pageId=54598262

Всё потому, что URL страниц в Confluence создается динамически, изменяясь «на лету» в зависимости от названия страницы.

А ссылки на страницы в Confluence существуют в системе как самостоятельные сущности (переменные). Поэтому привязываться надо не к ссылкам, а к сущностям, которые хранят в себе ссылки. Поэтому

Вставляем грамотно

1)

  1. Вызвать макрос ‘Insert Link’ (элементарно вызывается по Ctrl+K).
  2. В окне настроек выбрать Search > искать по названию страницы.

Будет мелкий неудобняк:

  • надо начинать набирать название искомой страницы без ошибок хотя бы в первых словах.
  • ой, если надо искать только что созданную страницу — она сперва должна проиндексироваться в системе, и процесс этот нам не подчиняется. Пока поиск не проиндексируется, будет казаться, что только что созданная страница тупо отсутствует…

Поэтому более точный и удобный способ: в окне настроек макроса ‘Insert Link’ открыть раздел ‘Recently viewed‘. Нужная страница там безусловно найдется, практически всегда окажется, что я её уже открывал. Клик по её ‘Title’, и всё готово.

Confluence Recently Viewed

Confluence Recently Viewed

Теперь название страницы, на которую поставлена ссылка, может изменяться как угодно, вплоть до появления ‘pageId=54598262‘ — ссылка всё равно сохраняется «живой и невредимой».

2)

Как быстро вставить ссылку, не подергивая свою мышь:

  1. В открытой на редактирование странице нажать на клавиатуре клавишу ‘[‘ — появится окно ‘Link suggestions’, аналог ‘Recently viewed’.

Дальше понятно?

Ссылки на имена юзеров вызываются через ‘@‘.

Вставлять картинки: через ‘!‘.

Можно внутри страницы организовать огневые перекрестные внутренние ссылки, что дичайше котируется в больших документах вроде ‘QA Vocabulary’ (например, в нашем 226 терминов, ой-вэй).

Ссылки на разделы внутри страницы

делаются так:

  1. Разметить текст как заголовок (в моем случае ‘Definitions of Selected Functional Verbs‘).

    Confluence Heading

    Confluence Heading

  2. Скопировать этот текст в буфер обмена as is. Со всеми его пробелами и запятыми, если есть.
  3. Перейти в другое место страницы, где надо сделать ссылку на данный заголовок.
  4. Вызвать макрос ‘Insert Link’ (элементарно вызывается по Ctrl+K).
  5. В окне настроек выбрать Advanced.
  6. В поле ‘Link’ своими руками вписать символ ‘#‘ и сразу текст (заголовок) из буфера обмена со всеми его пробелами, as is, буквально ‘#Definitions of Selected Functional Verbs
    Confluence Advanced Links

    Confluence Advanced Links

    // Внимание: The anchor name is case sensitive. You must use the same pattern of upper and lower case letters as you used when creating the Anchor.

    // После обработки текст превратится в #DefinitionsofSelectedFunctionalVerbs (ибо справка: The anchor name in the full URL is concatenated into a single word, with all spaces removed).

    // В поле ‘Link text’ автоматически будет вписан тот же текст. Его спокойно можно отредактировать, при этом содержимое поля ‘Link’ уже не изменится.

  7. Insert.

Итоговая ссылка на заголовок ‘Definitions of Selected Functional Verbs‘ будет выглядеть так: httр://confluence.test/display/~a.lupan/Action+Verbs+to+be+used+in+Goal+setting+process#ActionVerbstobeusedinGoalsettingprocess-DefinitionsofSelectedFunctionalVerbs

Мелкий неудобняк: ничто не подсказывает, что надо вставить ‘#‘. GTFO, если не знаешь про этот хинт. Я про него знаю, и вроде не дурак, но иногда забываю вписать эту чертову решеточку…

Серьезный, раздражающий неудобняк: если заголовок раздела ‘Definitions of Selected Functional Verbs‘ когда-нибудь изменится хоть на одну букву, ссылка внешне останется активной, но превратится в ссылку, просто закрытую заглушкой ‘#’.

Ок, это был простейший сценарий, ссылки внутри страницы. Теперь дело посложнее:

Поставить ссылку на заголовок с другой страницы, которая находится в другом space

Учли, что прямой Copy/Paste возможен, но потенциально недолговечен, и надо действовать через макрос ‘Insert Link’ (элементарно вызывается по Ctrl+K).

И пусть там можно найти только общий Title нужной страницы, внутренние ссылки оттуда недоступны, однако действовать надо именно через макрос ‘Insert Link’ (элементарно вызывается по Ctrl+K). Если в будущем изменится название страницы, в которой находится заголовок, на который надо ссылаться, Confluence эту ссылку грамотно обновит. Confluence рулит!

Вот если внтури страницы изменится тот самый внутренний заголовок, на который сделана «ссылка внутри страницы», тогда уж увы.

И всё равно придется действовать через раздел Advanced, да еще и вручную вписывать название страницы.

А это уже раздражающий неудобняк.

Если страница с внутренней ссылкой, на которую надо сослаться, находится в том же space:

  1. Вызвать макрос ‘Insert Link’ (элементарно вызывается по Ctrl+K) > Advanced
  2. Вставить ссылку по шаблону ‘Page Name#MyHeading‘.
  3. В моем случае это ‘Action Verbs to be used in Goal setting process#DefinitionsofSelectedFunctionalVerbs
  4. Insert.

Если страница с внутренней ссылкой, на которую надо сослаться, находится в другом space:

  1. Вызвать макрос ‘Insert Link’ (элементарно вызывается по Ctrl+K) > Advanced
  2. Вставить ссылку по шаблону ‘spacekey:Page Name#MyHeading‘.
  3. В моем случае это ‘~a.lupan:Action Verbs to be used in Goal setting process#DefinitionsofSelectedFunctionalVerbs
  4. Insert.

Работает.

ВНЕЗАПНОСТИ

1)

Полностью URL на определенный заголовок внутри определенной страницы выглядит так: httр://confluence.test/display/~a.lupan/Action+Verbs+to+be+used+in+Goal+setting+process#ActionVerbstobeusedinGoalsettingprocess-DefinitionsofSelectedFunctionalVerbs

Что же это за #ActionVerbstobeusedinGoalsettingprocess-DefinitionsofSelectedFunctionalVerbs, если я вписывал только #DefinitionsofSelectedFunctionalVerbs? Что за Wtf?

Ответ такой: все в порядке.

The page name is repeated in the URL, after the # sign. The second occurrence of the page name is concatenated into a single word, with all spaces removed.

Но зачем?

Ок, учтем, что в виде ссылки надо использовать только то, что идет за решеткой, но только после дефиса.

Неочевиднейший подход. Пока это поймешь…

2)

Если продолжить редактировать страницу, отсылка продолжает оставаться рабочей.

Но если я решу отредактировать эту ссылку… в ней исчезает spacekey, и вместо

~a.lupan:Action Verbs to be used in Goal setting process#DefinitionsofSelectedFunctionalVerbs

там будет написано

Action Verbs to be used in Goal setting process#DefinitionsofSelectedFunctionalVerbs‘.

Всё, ссылка сдохла.

Не обратишь на это пристальное внимание — увы, блеать…

Confluence Space Key Disappear

Confluence Space Key Disappear

3)

Confluence Help организован не по-взрослому.

Есть дефолт-справка по работе со ссылкам: https://confluence.atlassian.com/display/CONFEAP/Links

Но также зачем-то существуют отдельные страницы справка для разных версий Confluence. Например, справка для Confluenct версии 5.6 находится тут: https://confluence.atlassian.com/conf56/confluence-user-s-guide/creating-content/using-the-editor/working-with-links

Я работаю с Confluence 5.5.2, поэтому смотрю на https://confluence.atlassian.com/conf55/confluence-user-s-guide/creating-content/using-the-editor/working-with-links

Между всеми тремя версиями справки разницы НЕТ, количество слов в двух документах идентично. Wtf?

Confluence Help Links Word Count

Confluence Help Links Word Count

В целом Confluence рулит неимоверно!

Просто надо немного оторвать ноги/руки тем, кто реализовал механизм работы с ссылками, и мир во всем моем мире наступит.

Сразу.

Всей подошвой.

Ссылки в Confluence. Mazafaka: 8 комментариев

  1. Уведомление: DOU.UA QA дайджест #13: Последний выпуск уходящего года. Советы тестировщикам, новые инструменты и подходы к работе - Radio QA

  2. Уведомление: QA дайджест #13: Последний выпуск уходящего года. Советы тестировщикам, новые инструменты и подходы к работе - LIKELY.CLUB

  3. Nick

    Добрый день! А как узнать то самое имя spacekey если не я его создавал? Это то что я вижу в меню Spaces?

  4. Nick

    Hint: чтобы узнать имя пространства Confluence, надо зайти в это пространство и в левом нижнем углу нажать шестерёнку «Space tools»

  5. Anna

    Алексей, огромная благодарность. Мега-полезная статья, не потерявшая актуальность через семь с лишним лет 🙂 Спасибо!

  6. Alexei Lupan Автор записи

    Велком. Сам иногда к ней возвращаюсь.

  7. Natali Schetko

    Спасибо! Отличная статья

Добавить комментарий

Этот сайт использует Akismet для борьбы со спамом. Узнайте, как обрабатываются ваши данные комментариев.