Link examples to sections of the reference guide

[dwijnand]

From @gabro's https://twitter.com/gabro27/status/997815925041704960

Have you considered linking to the pertinent documentation section in between examples, so that people can get quickly to the details if they like?

[eed3si9n]

It would be good to style the reference links to indicate so that they don't have to read it initially.

Maybe using mechanism like this

Link to more details.

[dwijnand]

If you mean to not distract the user, I agree. But a clickable collapse-thingy is distracting because the user's is drawn to clicking it.

Maybe we can link the section title, or maybe a clickable icon like https://octicons.github.com/icon/book/.

[gabro]

Something like a quote block, with a standard structure would be good imho. A simple icon would easily go unnoticed. Something like:

📖 Learn about topic at hand in the docs

[gabro]

A concrete example:

---

Set ThisBuild / scalaVersion from sbt shell

sbt:foo-build> set ThisBuild / scalaVersion := "2.12.6"
[info] Defining ThisBuild / scalaVersion

Check the scalaVersion setting:

sbt:foo-build> scalaVersion
[info] 2.12.6

📖 Learn about ThisBuild and the other Scopes in the documentation