docs: redesigned code blocks (#2745)

* docs: redesigned code blocks to include titles

* docs: added a title where necessary
This commit is contained in:
Shahed Nasser
2022-12-08 18:52:54 +02:00
committed by GitHub
parent 8efae2dfcf
commit a57177ded5
60 changed files with 455 additions and 375 deletions
+61 -17
View File
@@ -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