Improve discoverability of environment variables

[mcanouil]

What would you like to do?

Give feedback or suggest an improvement

Description

The page about "Environment Variables" at https://quarto.org/docs/advanced/environment-vars.html is very hard to find because it has the same name as https://quarto.org/docs/projects/environment.html and is not linked in it.

It's linked in "Project Scripts": https://quarto.org/docs/projects/scripts.html

My suggestion is to fully include "/docs/advanced/environment-vars" as part of "docs/projects/environment" and update the link in "docs/projects/scripts" to point to "docs/projects/environment".

This will improve navigation as the "environment" page is in the navigation and will avoid issues in search.

[cderv]

My suggestion is to fully include "/docs/advanced/environment-vars" as part of "docs/projects/environment" and update the link in "docs/projects/scripts" to point to "docs/projects/environment".

I find that those two docs have different purposes. The docs/projects/environment is about the _environment feature that works for Project.

The other /docs/advanced/environment-vars is one of the first advanced user docs we have, but it is not structured yet.

So I would not merge the two documents.

Maybe we could have a callout: "If you're looking for an environment variable set or read by Quarto, see ..."

We could also try to find new name.

One of the first advanced user docs we have, but it is not structured yet.

I see it is not listed at all in the Advanced section

Maybe it is time to revisit the advanced section, and see how we can organize it better.

[mcanouil]

The rational about merging the two was driven by the fact that the "environment" page shows QUARTO_PYTHON, QUARTO_R, etc., but those are only described in "environment-vars" page and that the search mostly points to the "environment" page (not "environment-vars" page)

[cderv]

Oh, I see. This could be the story to link to the other doc: Here is the env var that matters to quarto that you could set in your _environment file