Fix some build errors related to mounted content #5352
Conversation
jdbaldry
added
type/docs
jdbaldry
force-pushed
the
jdb/2023-10-fix-links-to-flow-in-Grafana-Cloud
branch
from
c23384d to
fb4d56f
Compare
| @@ -106,3 +104,20 @@ one minor release is moved. | |||
| Patch and security releases may be created at any time. | |||
|
|
|||
| [Milestones]: https://github.com/grafana/agent/milestones | |||
|
|
|||
| {{% docs/reference %}} | |||
There was a problem hiding this comment.
Should we be using this block for all [link][] occurrences from now on?
There was a problem hiding this comment.
Linking is going through some changes to consolidate the various mechanisms.
https://grafana.com/docs/writers-toolkit/write/references/ contains the latest information and technical writers will also be able to advise as the recommendations evolve.
To answer your question, yes, for content mounted in Grafana Cloud like the Agent docs that might have different link destinations depending on where the page is rendered, use reference style links and the docs/reference shortcode.
There was a problem hiding this comment.
Thanks for the input.
Off-topic feedback, I feel like the docs pages have started to have more and more requirements such as multiple aliases, the description, this new block, or the note admonition. Once we've standardized all the mechanisms it'd be good to gather everything in one place (eg. in a sample page), or rethink if we need everything.
There was a problem hiding this comment.
For front matter like aliases and description, the reason for their existence is documented in https://grafana.com/docs/writers-toolkit/write/front-matter/. They have been required for a while but are not the highest priority, especially when a project doesn't have a dedicated technical writer.
The admonition shortcode is documented in https://grafana.com/docs/writers-toolkit/write/shortcodes/#admonition-shortcode and is intended to get consistent admonition styling across all our documentation.
The docs/reference shortcode is a more recent requirement to facilitate contextual link destinations because of the initiative to beef up Grafana Cloud content with relevant open-source documentation.
I think the changes feel sudden because Clayton has recently been a lot of good work to polish the docs.
There was a problem hiding this comment.
Yeah, didn't mean to bash on the changes by any means, just that it we'll have to find a way to keep track of them.
I think the changes feel sudden because Clayton has recently been a lot of good work to polish the docs
That's true, indeed he's been super proactive and helpful (@clayton-cornell 🙌)
There was a problem hiding this comment.
Oh yeah, I didn't mean to be defensive either!
I think communicating the changes effectively is a really important goal.
I will try and make sure that any PRs that introduce new or updated behavior have comprehensive descriptions that explain the reasoning and link to appropriate documentation :)
Another big plus one for Clayton's hard work!
Primarily arising from Flow content not being mounted in Grafana Cloud. Some were typos or incorrect relative paths. Signed-off-by: Jack Baldry <[email protected]>
jdbaldry
force-pushed
the
jdb/2023-10-fix-links-to-flow-in-Grafana-Cloud
branch
from
fb4d56f to
824dc6a
Compare
github-actions
bot
added
the
frozen-due-to-age
Primarily arising from Flow content not being mounted in Grafana Cloud.
Some were typos or incorrect relative paths.
Links for this PR and the backport tested in https://github.com/grafana/website/pull/15708.