@url

[aminya]

Adds @url which ease cross-linking to other parts of the web. This is handy when someone needs to reference different parts of a webpage multiple times. For example when some package wants to mention the docs of some other package, which is common in organizations.

Defined in meta:

BaseURLs = Dict("AcuteML" => "https://aminya.github.io/AcuteML.jl/dev/SyntaxReference")

Later in the docs, I can use the following for referencing to its different parts:

[some name](@url AcuteML/#AcuteML.@aml)

which builds the full URL for me:

https://aminya.github.io/AcuteML.jl/dev/#AcuteML.@aml

This is a simple feature which can indirectly fix #688

[mortenpi]

Sorry for not looking at this earlier. As I said in #1352, I don't think this conflicts with that one. This is actually kind of a workaround for the fact that the Julia Markdown parser doesn't support link reference definitions. A few thoughts:

1. Just bikeshedding: could also call it @link? As in, it doesn't necessarily have to be a full URL? E.g. maybe in the future this can be extended to support support computed external links? #1343, with user-defined functions generating the links.
2. I would be conservative with the URL keys, i.e. force them to match something like [A-Za-z0-9-].
3. Relatedly, I think at the moment it would break if your key is e.g. foo/bar and then then you have [](@url foo/bar/baz)?
4. Currently, I believe if you write [](@url foo), it appends a / to the reference URL? Probably best if it didn't, so that you could also use this feature to get the exact reference URL.

[mortenpi]

Another thing that would be nice to have is to be able to pass a document-global list of these URLs to makedocs.

[aminya]

Sorry for not looking at this earlier. As I said in #1352, I don't think this conflicts with that one. This is actually kind of a workaround for the fact that the Julia Markdown parser doesn't support link reference definitions. A few thoughts:

1. Just bikeshedding: could also call it @link? As in, it doesn't necessarily have to be a full URL? E.g. maybe in the future this can be extended to support support computed external links? #1343, with user-defined functions generating the links.

Sure. We can change it to @link.

2. I would be conservative with the URL keys, i.e. force them to match something like [A-Za-z0-9-].

🤔 that is a good idea! We can use IsURL.jl.

3. Relatedly, I think at the moment it would break if your key is e.g. foo/bar and then then you have [](@url foo/bar/baz)?
4. Currently, I believe if you write [](@url foo), it appends a / to the reference URL? Probably best if it didn't, so that you could also use this feature to get the exact reference URL.

I wanted to update that. The script should extract the main part of the URL no matter what the user writes (with or without ending /).

Another thing that would be nice to have is to be able to pass a document-global list of these URLs to makedocs.

I think it is better to not use meta altogether. makedocs is a better place in my opinion.

[mortenpi]

1. I would be conservative with the URL keys, i.e. force them to match something like [A-Za-z0-9-].

that is a good idea! We can use IsURL.jl.

Hmm, I am not sure we mean the same thing. I meant the keys of the BaseURLs dictionary that you use to refer to the actual URLs.

FWIW though, we have isabsurl in Documenter, so there would be no need for an extra dependency (we want to avoid unnecessary dependencies in Documenter).

I think it is better to not use meta altogether. makedocs is a better place in my opinion.

Since you already implemented it, I would keep it. I think it's good that you can define the URLs close to where you use them if you indeed only use them on one page. It would also be consistent with e.g. doctest filtering (which you can do either per-doctest, per-page or globally).

[aminya]

I'll take a look at this in one or two weeks. I've been quite busy lately.

[fredrikekre]

I think it would be much better with a general placeholder mechanism. No point in keeping this just for URL placeholders in references IMO.

[goerz]

It's a little bit of a hack, but DocumenterInterLinks (still experimental) could be used for something like this: Can I use this plugin for general external links?