Skip to content

docs(v2): improve cli docs #4259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slorber merged 8 commits into from
Feb 22, 2021
Merged

docs(v2): improve cli docs #4259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d3b3aaa
added more details about --danger flag for swizzle
massoudmaboudi Feb 21, 2021
061a3cf
added referencing to blog posts
massoudmaboudi Feb 21, 2021
cc4a320
improved the docs for swizzling.
massoudmaboudi Feb 22, 2021
f2deb4a
added new Farsi/Persian translation
massoudmaboudi Feb 22, 2021
73384b6
Update website/docs/cli.md
slorber Feb 22, 2021
4056f9b
Update website/docs/cli.md
slorber Feb 22, 2021
adc4ffa
Update website/docs/using-themes.md
slorber Feb 22, 2021
94fc7aa
PR cleanup
slorber Feb 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 17 additions & 5 deletions website/docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,18 +92,18 @@ We highly discourage swizzling of components until we've reached a Beta stage. T

:::

Change any Docusaurus theme components to your liking with `docusaurus swizzle`.
Change any Docusaurus theme components to your liking with `npm run swizzle`.

```shell
docusaurus swizzle [themeName] [componentName] [siteDir]
```bash npm2yarn
npm run swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
docusaurus swizzle @docusaurus/theme-classic DocSidebar
npm run swizzle @docusaurus/theme-classic DocSidebar
```

Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.

`docusaurus swizzle` without `themeName` lists all the themes available for swizzling similarly `docusaurus swizzle <themeName>` without `componentName` lists all the components available for swizzling.
`npm run swizzle` without `themeName` lists all the themes available for swizzling similarly `npm run swizzle <themeName>` without `componentName` lists all the components available for swizzling.

#### Options

Expand All @@ -114,6 +114,18 @@ Running the command will copy the relevant theme files to your site folder. You
| `--danger` | Allow swizzling of unstable components |
| `--typescript` | Swizzle TypeScript components |

An example to use `--danger` flag let's consider the below code:

```bash npm2yarn
npm run swizzle @docusaurus/theme-classic Logo -- --danger
```

:::caution

Unstable Components: components that have a higher risk of breaking changes due to internal refactorings.

:::

To unswizzle a component, simply delete the files of the swizzled component.

<!--
Expand Down
4 changes: 2 additions & 2 deletions website/docs/using-themes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,8 @@ Docusaurus Themes' components are designed to be replaceable. To make it easier

To swizzle a component for a theme, run the following command in your doc site:

```shell
docusaurus swizzle <theme name> [component name]
```bash npm2yarn
npm run swizzle <theme name> [component name]
```

As an example, to swizzle the `<Footer />` component in `@docusaurus/theme-classic` for your site, run:
Expand Down