yaml.markdown: Link configuration.yaml at first usage

[reedy]

Proposed change

Link to configuration.yaml's documentation at first usage

Type of change

• Spelling, grammar or other readability improvements (current branch).
• Adjusted missing or incorrect information in the current documentation (current branch).
• Added documentation for a new integration I'm adding to Home Assistant (next branch).
  • I've opened up a PR to add logo's and icons in Brands repository.
• Added documentation for a new feature I'm adding to Home Assistant (next branch).
• Removed stale or deprecated documentation.

Additional information

• Link to parent pull request in the codebase:
• Link to parent pull request in the Brands repository:
• This PR fixes or closes issue: fixes Where to find the configurtion.yaml.... #28924

Checklist

• This PR uses the correct branch, based on one of the following:
  • I made a change to the existing documentation and used the current branch.
  • I made a change that is related to an upcoming version of Home Assistant and used the next branch.
• The documentation follows the Home Assistant documentation standards.

[klaasnicolaas]

I don't think we need to merge this change, but that's mainly because we don't use text in single quotes as a link.

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[frenck]

because we don't use text in single quotes as a link.

I think we do?

Looking at this, I think it is smart and could be applied to any occurrence of configuration.yaml, as it provides help and more context to the ones that need it.

[reedy]

because we don't use text in single quotes as a link.

I think we do?

Pretty sure there's a few examples around, and not just what I may have introduced...

Looking at this, I think it is smart and could be applied to any occurrence of configuration.yaml, as it provides help and more context to the ones that need it.

Usually I find if it's a question that one newer person has had, it's a question that many others have had. And things you can do to make onboarding better/easier is always a good thing.

Can we do this a bit more automatically? Like as a build step, doing a string replace?

I suspect there might be a few other similar ones that could be beneficial.

Or would it require at least changing all usages/mentions like this into a template/variable or similar?

[frenck]

Can we do this a bit more automatically? Like as a build step, doing a string replace?

We should not. It can also be used in code snippets.

[reedy]

You mean you don't want to write a backtracking regex to look for whether we're in a code block? ;)

[frenck]

You mean you don't want to write a backtracking regex to look for whether we're in a code block? ;)

I mean we should just use Markdown and don't rely on magic.

[reedy]

Can this be merged then, as is?

[frenck]

We are awaiting @klaasnicolaas, he left this review. Please have patience, as most people do this in their spare time.

../Frenck

[klaasnicolaas]

I think we do?

I indeed see that we are applying it on more places, but that is more sporadic. Of course it is a good improvement, but perhaps we need to be consistent in how we handle links and highlighted text... it can be confusing.

But otherwise this PR is good to go for merging.

[frenck]

Alright, so agreed we can move forward I guess.

That said, this change is invalid nevertheless, as it links to itself 😉

../Frenck

[reedy]

Copy paste is hard (sometimes)!

[frenck]

Thanks, @reedy 👍

../Frenck

[frenck]

Thanks, @reedy 👍

../Frenck

[reedy]

I'll have a bit of a think about proliferating this a bit more throughout the other doc pages. Though, maybe as I'm making changes to other docs for other reasons, I can include a similar change to this too.

A very quick search suggests there's over 2000 mentions of the string configuration.yaml alone. But as you mention, numerous in code samples as parts of comments etc etc.