Skip to content

Commit

Permalink
docs: avoid using nested mdx-code-block (#7543)
Browse files Browse the repository at this point in the history
* docs: avoid using nested mdx-code-block

* fix
  • Loading branch information
Josh-Cena committed Jun 1, 2022
1 parent b81f80d commit 5cf6432
Show file tree
Hide file tree
Showing 6 changed files with 114 additions and 60 deletions.
46 changes: 31 additions & 15 deletions website/docs/blog.mdx
Expand Up @@ -192,9 +192,10 @@ Use the `authors` front matter field to declare blog post authors. An author sho

Blog post authors can be declared directly inside the front matter:

````mdx-code-block
```mdx-code-block
<Tabs groupId="author-front-matter">
<TabItem value="single" label="Single author">
<TabItem value="single" label="Single author">
```

```md title="my-blog-post.md"
---
Expand All @@ -207,8 +208,10 @@ authors:
---
```

</TabItem>
<TabItem value="multiple" label="Multiple authors">
```mdx-code-block
</TabItem>
<TabItem value="multiple" label="Multiple authors">
```

```md title="my-blog-post.md"
---
Expand All @@ -225,9 +228,10 @@ authors:
---
```

</TabItem>
```mdx-code-block
</TabItem>
</Tabs>
````
```

:::tip

Expand Down Expand Up @@ -279,28 +283,32 @@ Use the `authorsMapPath` plugin option to configure the path. JSON is also suppo

In blog posts front matter, you can reference the authors declared in the global configuration file:

````mdx-code-block
```mdx-code-block
<Tabs groupId="author-front-matter">
<TabItem value="single" label="Single author">
<TabItem value="single" label="Single author">
```

```md title="my-blog-post.md"
---
authors: jmarcey
---
```

</TabItem>
<TabItem value="multiple" label="Multiple authors">
```mdx-code-block
</TabItem>
<TabItem value="multiple" label="Multiple authors">
```

```md title="my-blog-post.md"
---
authors: [jmarcey, slorber]
---
```

</TabItem>
```mdx-code-block
</TabItem>
</Tabs>
````
```

:::info

Expand Down Expand Up @@ -394,9 +402,10 @@ The default reading time is able to accept additional options: `wordsPerMinute`

Use the callback for all your customization needs:

````mdx-code-block
```mdx-code-block
<Tabs>
<TabItem value="disable-per-post" label="Per-post disabling">
```

**Disable reading time on one page:**

Expand All @@ -410,7 +419,9 @@ module.exports = {
showReadingTime: true,
// highlight-start
readingTime: ({content, frontMatter, defaultReadingTime}) =>
frontMatter.hide_reading_time ? undefined : defaultReadingTime({content}),
frontMatter.hide_reading_time
? undefined
: defaultReadingTime({content}),
// highlight-end
},
},
Expand All @@ -429,8 +440,10 @@ hide_reading_time: true
This page will no longer display the reading time stats!
```

```mdx-code-block
</TabItem>
<TabItem value="passing-options" label="Passing options">
```

**Pass options to the default reading time function:**

Expand All @@ -452,8 +465,10 @@ module.exports = {
};
```

```mdx-code-block
</TabItem>
<TabItem value="using-custom-algo" label="Using custom algorithms">
```

**Use a custom implementation of reading time:**

Expand All @@ -475,9 +490,10 @@ module.exports = {
};
```

```mdx-code-block
</TabItem>
</Tabs>
````
```

:::

Expand Down
21 changes: 15 additions & 6 deletions website/docs/deployment.mdx
Expand Up @@ -302,31 +302,37 @@ GitHub enterprise installations should work in the same manner as github.com; yo

Finally, to deploy your site to GitHub Pages, run:

````mdx-code-block
```mdx-code-block
<Tabs>
<TabItem value="bash" label="Bash">
```

```bash
GIT_USER=<GITHUB_USERNAME> yarn deploy
```

```mdx-code-block
</TabItem>
<TabItem value="windows" label="Windows">
```

```batch
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
```

````mdx-code-block
</TabItem>
<TabItem value="powershell" label="PowerShell">
```mdx-code-block

```powershell
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
```
````

```mdx-code-block
</TabItem>
</Tabs>
````
```
:::caution
Expand All @@ -352,16 +358,16 @@ Here are two approaches to deploying your docs with GitHub Actions. Based on the
- Source repo and deployment repo are the **same** repository.
- The deployment repo is a **remote** repository, different from the source.
````mdx-code-block
```mdx-code-block
<Tabs>
<TabItem value="same" label="Same">
```

While you can have both jobs defined in the same workflow file, the original `deploy` workflow will always be listed as skipped in the PR check suite status, which is not communicative of the actual status and provides no value to the review process. We therefore propose to manage them as separate workflows instead.

We will use a popular third-party deployment action: [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus).

<details>

<summary>GitHub action files</summary>

Add these two workflow files:
Expand Down Expand Up @@ -446,8 +452,10 @@ jobs:

</details>

```mdx-code-block
</TabItem>
<TabItem value="remote" label="Remote">
```

A cross-repo publish is more difficult to set up, because you need to push to another repo with permission checks. We will be using SSH to do the authentication.

Expand Down Expand Up @@ -517,9 +525,10 @@ jobs:

</details>

```mdx-code-block
</TabItem>
</Tabs>
````
```
### Triggering deployment with Travis CI {#triggering-deployment-with-travis-ci}
Expand Down
Expand Up @@ -47,6 +47,7 @@ Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
```

```mdx-code-block
<BrowserWindow>
:::note
Expand Down Expand Up @@ -80,6 +81,7 @@ Some **content** with _markdown_ `syntax`. Check [this `api`](#).
:::
</BrowserWindow>
```

## Usage with Prettier {#usage-with-prettier}

Expand Down Expand Up @@ -115,6 +117,7 @@ Some **content** with _markdown_ `syntax`.
:::
```

```mdx-code-block
<BrowserWindow>

:::note Your Title
Expand All @@ -124,6 +127,7 @@ Some **content** with _markdown_ `syntax`.
:::

</BrowserWindow>
```

## Admonitions with MDX {#admonitions-with-mdx}

Expand All @@ -145,21 +149,21 @@ import TabItem from '@theme/TabItem';
:::
```
```mdx-code-block
<BrowserWindow>
:::tip Use tabs in admonitions
```mdx-code-block
<Tabs>
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
<TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
<TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
</Tabs>
```
:::
</BrowserWindow>
```

## Usage in JSX {#usage-in-jsx}

Expand Down Expand Up @@ -190,6 +194,7 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
</Admonition>
```

```mdx-code-block
<BrowserWindow>
<Admonition type="tip" icon="💡" title="Did you know...">
<p>
Expand All @@ -198,3 +203,4 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
</p>
</Admonition>
</BrowserWindow>
```

0 comments on commit 5cf6432

Please sign in to comment.