Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: make description consistent with link-external-filter example code #1332

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: make description consistent with link-external-filter example code #1332

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions docs/output-formats/html-basics.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -326,19 +326,19 @@ format:

By default external links (i.e. links that don't target the current site) receive no special visual adornment or navigation treatment (the current page is navigated). You can use the following options to modify this behavior:

+---------------------------+--------------------------------------------------------------------------------------------------------------------+
| Option | Description |
+===========================+====================================================================================================================+
| `link-external-icon` | `true` to show an icon next to the link to indicate that it's external (e.g. [external](#){.external}). |
+---------------------------+--------------------------------------------------------------------------------------------------------------------+
| `link-external-newwindow` | `true` to open external links in a new browser window or tab (rather than navigating the current tab). |
+---------------------------+--------------------------------------------------------------------------------------------------------------------+
| `link-external-filter` | A regular expression that can be used to determine whether a link is an internal link. For example |
| | |
| | `^(?:http:|https:)\/\/www\.quarto\.org\/custom` |
| | |
| | will treat links that start with http://www.quarto.org as internal links (and others will be considered external). |
+---------------------------+--------------------------------------------------------------------------------------------------------------------+
+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Option | Description |
+===========================+================================================================================================================================================================+
| `link-external-icon` | `true` to show an icon next to the link to indicate that it's external (e.g., [external](#){.external}). |
+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `link-external-newwindow` | `true` to open external links in a new browser window or tab (rather than navigating the current tab). |
+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `link-external-filter` | A regular expression that can be used to determine whether a link is an internal link. For example |
| | |
| | `^(?:http:|https:)\/\/www\.quarto\.org\/custom` |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "custom" in this example looks a bit weird imho. It's not a common url part. Why not make it a little more concrete and self-explanatory by changing it to be about www.quarto.org/docs or something alike?

And to be really nitpicky: I would also change the domain to something non-quarto, e.g. www.example.com, which is designed for exactly these kind of things

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue was that it was not consistent. Changing "custom" to "docs" or "whatever" does not change/improve anything. Same as using example.com.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does not change/improve anything.

  • changing /custom to /docs improves the familiarity and self-explanatory nature of the snippet (I've never seen /custom being used as top-level path components in docs)
  • changing quarto.org to example.com makes it more clear that you have to put your own URL there, not the URL of the software you are using. The domain example.com is explicitly being defined for documentation purposes like this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

example.com does not have pages beside index.html.

You seem to want to restrict the example to be what you know/expect rather that for it to be whatever regular expressions allows.
It's a regular expression, if "you" don't understand what it is, using example.com or quarto.org/docs in the example won't change anything.

Here, Carlos' comment applies:

The confusion can be solved by experimenting with the option, and understanding regexes are necessary to using them.

I won't make changes here until one of the maintainers makes a review.
As I said, the goal is was to fix the inconsistency and not to change the whole example.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nevermind. I was just trying to help improve the docs based on my first hand experience trying to make sense of the example.
And I have plenty of regex experience, that wasn't even the issue to begin with.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear, what I'm saying is that I don't want to make more changes without having the feedback of the maintainers first, not that your feedback is not valuable.

| | |
| | will treat links that start with `http://www.quarto.org/custom` or `https://www.quarto.org/custom` as internal links (and others will be considered external). |
+---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+

External links are identified either using the `site-url` (if provided) or using the `window.host` if no `site-url` or `link-external-filter` is provided. For example, here we enable both options and a custom filter:

Expand Down
Loading