aws-amplify / aws-amplify/docs

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

Open
#4,972 1 comment 0 reactions 0 assignees View on GitHub
amplify/content
Dominant language
MDX
Stars
506
Forks
1.1k
Avg merge
3h 14m
Merged PRs (30d)
1

Description

**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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.