Add plugin to skip command linker

[yathomasi]

By default, our command line linkers always link any inline code based on dvc, cml, ... our tools.

If we want to customize them we can always wrap the inline code with a link eg:

[`dvc ...`](link)

This PR adds a plugin to allow us to have no link at all. For that, we can pass no value. eg:

[`dvc ...`]()

closes iterative/cml.dev#424

[rogermparent]

I don't really love the solution of adding a remark plugin with new syntax to override the auto-linker instead of constraining what the auto-linker operates on, but if @iterative/docs feels differently I won't stand in the way. If nothing else, it could be a decent mid-ground and it won't be very difficult to backport empty links after adjusting autolinker behavior.

[yathomasi]

constraining what the auto-linker operates on

We have a constraint on linking when there is inline code with cml|dvc|...tools and their subcommand exists or if there is an option we do check if they exist. So, I don't see how we can constrain it more from the auto-linker side.

Also, we already use links to override the autogenerated links. So, passing an empty value to ignore auto-link seemed a good approach to me.

[rogermparent]

So, I don't see how we can constrain it more from the auto-linker side.

As far as I understand, the originally suggested constraint when this was proposed is

cml thingy --flag correctly links to /doc/ref/thingy#--flag but cml thingy --flag --another-flag really shouldn't IMO.

It seems to me like auto-linking only code blocks with a single flag would be the most expected, unless there is a good reason to auto-link commands with more than one flag instead of manually linking those cases (@iterative/docs may be able to think of an example). Using [link]() feels like it should be more of a last resort on something that would otherwise definitely be linked, and I also don't see a lot of that use case if we implement the former behavior.

This feature makes sense, at least in the current context, but even then saying that all multi-flag code examples should use it feels a bit too intrusive.

[yathomasi]

I could only find a similar case scenario in dvc.org

• https://dvc.org/doc/api-reference/dvcfilesystem#listing-all-dvc-tracked-files-recursively
  • dvc ls --recursive --dvc-only

If we want to fully ignore the command line linker in a similar case scenario then feel free to open a ticket and continue with the discussion.
Personally, I would allow the linker as these are rare and the current solution [`skip command linker`]() would allow the skip if we want.

cc: @iterative/docs

[jorgeorpinel]

auto-linking only code blocks with a single flag would be the most expected, unless there is a good reason to auto-link commands with more than one flag

OK, I guess it's a separate Q from #156 (that one is more about whether the subcommands and flags actually exist). BTW, should we move it to this repo?

To answer the Q, I think a decent default behavior would be to link to the specific option only when there's a single flag indeed, but still link to the general ref. page if there are more (due to ambiguity). Other options:

• Always link to the general page
• Always link to #options if there are flags present

[yathomasi]

BTW, should we move it to this repo?

Sure, we can move it here as core logic is here.

To answer the Q, I think a decent default behavior would be to link to the specific option only when there's a single flag indeed, but still link to the general ref. page if there are more (due to ambiguity). Other options:

• Always link to the general page
• Always link to #options if there are flags present

Yes, I agree with this and it works as mentioned except for multiple options. Right now, it links to the first option from the multiple options and ignores anything more. But, as mentioned such usage is rare for us.