LINUX.ORG.RU

Относительные ссылки в wiki на Bitbucket

 , , ,


0

1

У кого-нибудь есть опыт работы с битбакетом в плане документирования? У меня возникли проблемы с относительными ссылками между страницами вики проекта и файлами в репозитории. После нескольких часов мучений обнаружил, что это известная проблема, имеющая длинную историю.

Чего я не могу добиться: постоянной (не зависящей от хеша коммита) и при этом относительной (работающей даже в склонированном вики-репозитории, который рендерится pandoc'ом локально) ссылки с вики-страницы на файл в репозитории. Перепробовал уже десяток вариантов. Некоторые работают в предварительном просмотре, а при записи страницы — ломаются, некоторые — работали раньше (в прошлые годы, судя по комментариям), а теперь не работают...

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

Интересует существующий опыт и актуальные общепринятые практики, касающиеся описываемого случая. Спасибо!

★★

Последнее исправление: TwisteR (всего исправлений: 1)

мы просто забили это, делаем документацию в маркдауне, и расширили парсер маркдауна такими ссылками, которые умеют как нам хочется. (ясно что такой модифицированный маркдаун битбакетом не парсится). После рендеринга маркдауна в HTML, его можно залить в Конфлюенс силами Конфлюенс API. Пере-рендеринг в HTML и заливку надо делать при новых коммитах в master/devel ветку, например джобой в Дженкинсе

stevejobs ★★★★☆
()
Последнее исправление: stevejobs (всего исправлений: 2)

У меня документация в виде файлов markdown, содержащихся в самом репозитории. вот тут есть пример ссылки на файл в той же директории (ищи в тексте слова «More searching examples are in the user manual.») . Ссылка без хеша в битбукете в принципе выглядит так:

https://bitbucket.org/budden/clcon/src/default/doc/demo-tour.md?fileviewer=fi...

В Вики у меня только галереи картинок, не являющиеся частью исходного текста и не имеющие большой ценности.

Может быть, ты сможешь Когда мне понадобилось, чтобы мой markdown был виден как html, я воспользовался сервисом githack:

https://bb.githack.com/budden/yar/raw/default/doc/описание-языка/сгенерирован...

Там есть два режима - production и development, для часто обновляющихся файлов лучше development.

den73 ★★★★★
()
Ответ на: комментарий от den73

Ссылка без хеша в битбукете в принципе выглядит так:

Да, но она не будет работать в локальной копии, а в форке будет ссылаться на оригинал... И вообще, абсолютные ссылки на файлы этого-же репозитория — дикость какая-то. Так не должно быть. Не могу поверить, что атлассиану на это пофиг.

мы просто забили это, делаем документацию в маркдауне, и расширили парсер маркдауна такими ссылками, которые умеют как нам хочется.

ололо

TwisteR ★★
() автор топика
Ответ на: комментарий от TwisteR

В тексте ссылки просто написано [demo tour](demo-tour.md) . Ситуцаии, когда понадобилось сослаться на другую директорию, у меня не было

den73 ★★★★★
()
Ответ на: комментарий от den73

В общем, вроде бы решил проблему. Надо было всего-то отступить на один уровень (поскольку в вики к относительным ссылкам добавляется /wiki/...):

[относительная wiki-ссылка на каталог ololo в корне репозитория проекта](../src/master/ololo/)

Есть одно мелкое неудобство (которое сбивало меня с толку поначалу): такая ссылка не будет работать в preview, зато отлично будет работать после коммита. master — ветка, на которую ссылаемся.

Такие ссылки будут вполне корректно работать локально, если сделать симлинк ../src/master (и/или другие интересующие вас ветки, относительно каталога wiki), указывающий на корень репозитория.

TwisteR ★★
() автор топика
Ответ на: комментарий от TwisteR

Круто, жаль, что я это раньше не знал. Хотя на самом деле и то, что у меня получилось (md) - тоже хорошо - можно грепить документацию и сорсы одной командой, что я и делаю постоянно.

den73 ★★★★★
()
Ответ на: комментарий от den73

Так у меня тоже всё в .md. Там ведь можно склонировать всю вики себе локально. Она основана на той-же VCS, что и проект. Все страницы в ней — отдельные файлы .md, а правки — коммиты.

git clone git@bitbucket.org:team/project.git/wiki

Потом править в любом удобном редакторе, просматривать (опционально, через любой локальный рендер), коммитить и пушить обратно.

TwisteR ★★
() автор топика
Последнее исправление: TwisteR (всего исправлений: 1)
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.