Skip to content

Create spoken form widget for use in docs #2232

Open
@pokey

Description

@pokey

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 the paste action, the to destination, and a page for air 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions