Skip to content

styleguide suggestion: fenced code blocks should be succinct, contain necessary imports #4972

Open
@josefaidt

Description

@josefaidt

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

When reading the documentation and encountering code samples, it would be nice if we are able to copy and paste these samples into a file without issue. In short we should aim for:

  • consistency
  • copy/paste-ability

Describe the solution you'd like
A clear and concise description of what you want to happen.

Add a section to the styleguide to enforce the following for fenced code blocks:

  • code blocks should use consistent code style
    • naming convention of variables
    • use of whitespace (e.g. JavaScript imports should be followed by a newline)
  • code blocks in the same page/space should be consistent in use of imports (e.g. using graphqlOperation)
  • code blocks should contain all imports necessary (i.e. if the sample contains usage of API, sample should also include the API import statement)
  • code blocks should contain a sample filename
    • when using relative imports we should provide a sample filename based on the project defaults (e.g. include // src/App.jsx where we aim to import the sibling ./aws-exports
  • code blocks should be formatted with the prettier config from this repo

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions