Problem description
Relative links are useless for man and terminal representations, rendering them is very distracting.
But disabling links also disables web links.
Proposal
Add an option to only render web link URLs while keeping relative links highlighted.
Background
The Nix package manager uses lowdown to render man and --help pages.
The manual also renders as a web page and uses relative links for navigation (example). It also contains web links (example).
Currently there is no straightforward way to render the manual both for web and terminal without losing information or introducing a lot of noise on the terminal: either turn off links, then weblinks are gone, or turn on links, then the useless relative links to markdown files pollute every page.
Broken example when links enabled:
Synopsis
nix [option…] subcommand
where subcommand is one of the following:
Main commands:
• nix build (./nix3-build.md) - build a derivation or fetch a store path
• nix develop (./nix3-develop.md) - run a bash shell that provides the
build environment of a derivation
How it should be:
Synopsis
nix [option…] subcommand
where subcommand is one of the following:
Main commands:
• nix build - build a derivation or fetch a store path
• nix develop - run a bash shell that provides the
build environment of a derivation
Broken example when links disabled:
Description
Nix is a tool for building software, configurations and other artifacts in a
reproducible and declarative way. For more information, see the Nix homepage
or the Nix manual.
How it should be:
Description
Nix is a tool for building software, configurations and other artifacts in a
reproducible and declarative way. For more information, see the Nix homepage
(https://nixos.org/) or the Nix manual (https://nixos.org/manual/nix/stable/).
More background
It appears @edolstra decided to use lowdown because it has no dependencies and does the job. I think it does a great job, as it allows the project to manage documentation in a uniform, easily accessible format and make it available in different contexts. Thank you for this tool, it's really well documented and easy to use.
The Nix ecosystem has a reputation of terrible documentation, and I work on improving it. Since all the different representations go through one build process, I got stuck with this problem while trying to clean it up. The goal of my refactoring attempt was easing maintenance of documentation, making it more accessible even to occasional contributors.
I tried working around the issue within the build setup, but it already is a tangled mess. It appears easier and more sustainable to add a feature to lowdown than manually fighting such a recurring pattern, which a markdown processor is much more suitable to deal with.
Problem description
Relative links are useless for
manand terminal representations, rendering them is very distracting.But disabling links also disables web links.
Proposal
Add an option to only render web link URLs while keeping relative links highlighted.
Background
The Nix package manager uses
lowdownto rendermanand--helppages.The manual also renders as a web page and uses relative links for navigation (example). It also contains web links (example).
Currently there is no straightforward way to render the manual both for web and terminal without losing information or introducing a lot of noise on the terminal: either turn off links, then weblinks are gone, or turn on links, then the useless relative links to markdown files pollute every page.
Broken example when links enabled:
How it should be:
Broken example when links disabled:
How it should be:
More background
It appears @edolstra decided to use
lowdownbecause it has no dependencies and does the job. I think it does a great job, as it allows the project to manage documentation in a uniform, easily accessible format and make it available in different contexts. Thank you for this tool, it's really well documented and easy to use.The Nix ecosystem has a reputation of terrible documentation, and I work on improving it. Since all the different representations go through one build process, I got stuck with this problem while trying to clean it up. The goal of my refactoring attempt was easing maintenance of documentation, making it more accessible even to occasional contributors.
I tried working around the issue within the build setup, but it already is a tangled mess. It appears easier and more sustainable to add a feature to
lowdownthan manually fighting such a recurring pattern, which a markdown processor is much more suitable to deal with.