docs: redesigned code blocks (#2745)
* docs: redesigned code blocks to include titles * docs: added a title where necessary
This commit is contained in:
@@ -93,32 +93,76 @@ If the admonition does not match any of the mentioned criteria, always default t
|
||||
|
||||
If you are adding images to a documentation page, you can host the image on [Imgur](https://imgur.com) for free.
|
||||
|
||||
## Code Block Types
|
||||
## Code Blocks
|
||||
|
||||
In the Medusa documentation, there are two code block types: code blocks with headers and code blocks without headers.
|
||||
### Use Tabs with Code Blocks
|
||||
|
||||
Code blocks without headers should be used when:
|
||||
To use Tabs with Code Blocks, you have to use [Docusaurus's `Tabs` and `TabItem` components](https://docusaurus.io/docs/markdown-features/code-blocks#multi-language-support-code-blocks).
|
||||
|
||||
- The code block is used inside an Admonition.
|
||||
- The content of the code block can't be reported (for example, if the code block contains only a text of the expected output).
|
||||
You must also pass to the `Tabs` component the prop `wrapperClassName="code-tabs"` to ensure correct styling.
|
||||
|
||||
In all other cases, code blocks with headers should be used.
|
||||
|
||||
### Code Blocks with Headers
|
||||
|
||||
By default, all code blocks have headers and no additional actions are required to add the header.
|
||||
|
||||
### Code Blocks without Headers
|
||||
|
||||
To add a code block without a header, simply add `noHeader` after the beginning backticks of the code block. For example:
|
||||
For example:
|
||||
|
||||
~~~md
|
||||
```bash noHeader
|
||||
this code block does not have a header
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```jsx
|
||||
medusa.admin.uploads.create(file) //file is an instance of File
|
||||
.then(({ uploads }) => {
|
||||
const key = uploads[0].key;
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<YOUR_SERVER>/admin/uploads' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: text/csv' \
|
||||
-F 'files=@"<FILE_PATH_1>"'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
~~~
|
||||
|
||||
### Add Title to Code Block with Tabs
|
||||
|
||||
If you want to add a title to a code block with tabs, add the `codeTitle` prop to the `Tabs` component.
|
||||
|
||||
For example:
|
||||
|
||||
```md
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs" codeTitle="/src/services/hello.ts">
|
||||
```
|
||||
|
||||
### Add Title to Code Block without Tabs
|
||||
|
||||
To add a title to a code block without tabs:
|
||||
|
||||
~~~md
|
||||
```js title=src/index.ts
|
||||
console.log("hello")
|
||||
```
|
||||
~~~
|
||||
|
||||
`noHeader` should be added after the language of the code block (which is `bash` in the above example). If you used `npm2yarn` as well, `noHeader` should be after it.
|
||||
### Remove Report Buttons
|
||||
|
||||
Some code block don't need a report button. To remove the report button, use the `noReport` metadata.
|
||||
|
||||
For example:
|
||||
|
||||
~~~md
|
||||
```bash noReport
|
||||
medusa new my-medusa-store --seed
|
||||
```
|
||||
~~~
|
||||
|
||||
## NPM and Yarn Code Blocks
|
||||
|
||||
|
||||
Reference in New Issue
Block a user