Open
Description
It would be nice if all of the example commands in our docs were represented in a structured way. That would allow the following:
- They could automatically reflect the latest spoken forms
- They could use user's custom spoken forms
- We could link to definition of each component of the command, eg in
"paste to air"
we could link to thepaste
action, theto
destination, and a page forair
which starts with "air is the generic target used in examples" and a link to talon alphabet and then more. Could also support hover - Could have backlinks where we can see all places where an action is used
- We could possibly show keyboard sequence?
The solution
We'd like to leverage the grammar proposed in #492. The question remains how we surround this syntax in our .md
doc files. Note that our .md
files are actually mdx
Possible syntaxes:
`"paste to air"`
<Command>paste to <ExampleTarget/></Command>
<Command>paste to {exampleTarget}</Command>
<Command>
paste to {exampleTarget}
</Command>
{command("paste to <exampleTarget>")}
{command`paste to <exampleTarget>`}
{$`paste to <exampleTarget>`}
<Command>paste <ExampleDestination/></Command>
<Command text="paste to <exampleTarget>"/>
@AndreasArvidsson and I discussed, and we lean towards just supporting the exact syntax we're using today (`"paste to air"`
). We could detect these during postprocessing (same machinery we use to canonicalize our links) and convert them to something richer. The biggest benefit is that it gives us an excuse to just keep using the existing syntax for now as we continue to expand the docs