We will also need to introduce CSS overrides like in NixOS/nixpkgs#77683 and make them included in the manual like NixOS one does.

Edit: Copied my changes from there, without the callout changes since Nix no longer (858ad7a) builds graphical callouts – we should probably fix re-introduce them in more sane way.

Confirmed it works by building Nix with nix-build ./release.nix -A build.x86_64-linux.all and then finding the first prompt in result-doc/share/doc/nix/manual/index.html:

Note that if we're going to convert to Markdown or RST, then we're probably going to lose semantic markup like this.

It shouls still work in MDX. With reST we would need to define a custom prompt role for use withing parsed-literal but it should work there too.

Can we merge it in the meanwhile?

It's not an issue of whether we can do it in ReST / Markdown. Part of the reason for switching away from DocBook is to have less semantic markup, to make it easier to contribute to the documentation. Most contributors will not get this markup right so we end up with inconsistent formatting. (Also, whereas DocBook is strict about errors in markup, Markdown interpreters generally silently ignore errors. So that's another reason for avoiding special formatting directives as much as possible.)

I am not sure having less semantic markup is a good goal to have. Contribution can be made easier by making the critical path (like paragraphs, lists or links) easier to do, while still having a way to do more complex things for people who are so inclined. In particular, this feature offers a nice usability improvement while only increasing the grammar complexity minutely and in a localised way (only within code literals).

Inconsistent formatting will be an issue but that is precisely the trade-off we choose to accept when switching to more a lenient language – more work for humans, just made optional so that people who are unable to handle it do not have to. Not that much would change regarding <prompt> – people are unaware of it now and it just needs to be manually added like it would need to be manually added in reST.

I would still like to merge this for now. If we decide that having prompts annotated is not worth it, we can always just strip them during the migration. Though, even the redesigned homepage still has non-selectable prompts so the marketing team probably sees some advantage too. Also, last time I heard, Nix manual was not considered part of the initial docs revamp effort, so maybe this small usability improvement could be here for a while.

I'll close this since highlight.js gives us highlighting of prompts in shell sessions (see e.g. https://hydra.nixos.org/build/124655688/download/1/manual/quick-start.html).

Unfortunately, that does not work for [nix-shell:~]$ prompts, nor does it allow us to make the prompts unselectable, which is the main reason I opened this PR in the first place.

That could probably be done by tweaking the highlighter.