I don't understand what happened here?
I only had these files changed/added:

• src/applications/reference/src/application/ReferenceApplication.php
• src/applications/reference/src/controller/CowayReferenceController.php
• src/applications/reference/src/controller/FigletReferenceController.php
• src/applications/reference/src/controller/ReferenceController.php
• src/applications/reference/src/controller/RemarkupReferenceController.php
• src/infrastructure/markup/interface/RemarkupSyntaxDocumentationProvider.php
• src/infrastructure/markup/interpreter/PhabricatorRemarkupCowsayBlockInterpreter.php
• src/infrastructure/markup/interpreter/PhabricatorRemarkupFigletBlockInterpreter.php
• src/view/form/control/PhabricatorRemarkupControl.php

I ran git pull and arc diff and it complained about 2 unit tests (some line with only blanks, which I think should have been untouched):

• src/infrastructure/markup/remarkup/__tests__/remarkup/tick-block-multi-flavored-comment.txt
• src/infrastructure/markup/remarkup/__tests__/remarkup/tick-block-multi-flavored.txt

I'm suprised it changed more than 1000 files by magic ?

It also collected lots of commits, since May 2023.

I think these commits have different hashes from the hashes in here - maybe you had a strange merge/rebase issue.

maybe try git rebase origin master to get rid of the duplicate commits? maybe rebase -i.

Looks good! I want to play with it locally before accepting.

Is there an "index" page?

I did not add a real index page.
The remarkup reference acts a bit as index page as cowsay and figlet references are referenced in here as hyperlinks.

The document generation for cowsay and figlet, which consisted this phutil_get_library_root('phabricator')) code, was copied from PhabricatorRemarkupCowsayBlockInterpreter.php and PhabricatorRemarkupFigletBlockInterpreter.php.
These are btw not the only locations:

grep -r "phutil_get_library_root(.phabricator.))" | wc -l

Ok, this looks much better then what we have today, so yay.

One odd thing, I think the line-break logic is different between the Diviner and this rendering:

Diviner	This diff

Maybe a clue in https://we.phorge.it/source/phorge/browse/master/src/applications/diviner/controller/DivinerAtomController.php$633 ?

In my mind, we would also find all available rules, and each one will be able to create its own page (the simple ones will not, and will have basically the front page as it is now to handle them).

I think the next steps:

• Mark this diff as "Refs" the task rather then "Closes"
• Land this, with maybe some small changes
• Later, do a revision where we add an index and automatically create a page for each instance of RemarkupSyntaxDocumentationProvider and/or RemarkupRule.

Re phutil_get_library_root: We didn't update most calls for because they weren't urgent (not user-facing), and we needed the magic anyway (for extensions), but when we touch them it's a good time to move them.

I love this at unbelievable level, thanks all 🌈

Small possible minor things:

1. I noticed the cowsay joke generator. It's lovely but it's a pity that most Remarkup is cached so I usually just see one while visiting /reference/remarkup/ - and I think this caching system should not be removed. Next step: maybe this may become a cowsay Motivator generator (http://phorge.localhost/home/menu/new/custom/motivator/)
2. Probably the page /reference/figlet/ should add a small link back to the home Remarkup page + same for cowsay
3. probably we can avoid the link «here» that is a bit not semantic, and we can have instead a link called «See the cowsay documentation» and same for figlet

Congrats to this patch.

In D25698#19289, @valerio.bozzolan wrote:

3. probably we can avoid the link «here» that is a bit not semantic, and we can have instead a link called «See the cowsay documentation» and same for figlet

Yeah I'd appreciate a followup because https://www.w3.org/TR/WCAG20-TECHS/F84.html or https://www.w3.org/QA/Tips/noClickHere :)