Skip to content

Commit

Permalink
docs: add page for create-docusaurus API documentation (#7343)
Browse files Browse the repository at this point in the history
* docs: add page for create-docusaurus API documentation

* update
  • Loading branch information
Josh-Cena authored May 5, 2022
1 parent dd4b7c8 commit 0cc4fa8
Show file tree
Hide file tree
Showing 4 changed files with 63 additions and 23 deletions.
57 changes: 57 additions & 0 deletions website/docs/api/misc/create-docusaurus.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
sidebar_position: 0
title: '📦 create-docusaurus'
slug: '/api/misc/create-docusaurus'
---

A scaffolding utility to help you instantly set up a functional Docusaurus app.

## Usage {#usage}

```bash
npx create-docusaurus@latest [name] [template] [rootDir]
```

The `name` argument will be used as the site's path as well as the `name` field in the created app's package.json. It can be an absolute path, or a path relative to `rootDir`.

The `template` argument can be one of the following:

- `classic`: Uses the classic template (recommended)
- `facebook`: Uses the Facebook/Meta template, which contains some Meta-specific setup
- A git repo URL (beginning with `https://` or `git@`), which can be cloned to the destination
- A local file path relative to CWD, which contains the files to be copied to destination

The `rootDir` will be used to resolve the absolute path to the site directory. The default is CWD.

:::caution

This command should be preferably used in an interactive shell so all features are available.

:::

## Options {#options}

### `-t, --typescript` {#typescript}

Used when the template argument is a recognized name. Currently, only `classic` provides a TypeScript variant.

### `-g, --git-strategy` {#git-strategy}

Used when the template argument is a git repo. It needs to be one of:

- `deep`: preserves full git history
- `shallow`: clones with `--depth=1`
- `copy`: does a shallow clone, but does not create a git repo
- `custom`: enter your custom git clone command. We will prompt you for it. You can write something like `git clone --depth 10`, and we will append the repository URL and destination directory.

### `-p, --package-manager` {#package-manager}

Value should be one of `npm`, `yarn`, or `pnpm`. If it's not explicitly provided, Docusaurus will infer one based on:

- The lockfile already present in the CWD (e.g. if you are setting up website in an existing project)
- The command used to invoke `create-docusaurus` (e.g. `npm init`, `npx`, `yarn create`, etc.)
- Interactive prompting, in case all heuristics are not present

### `-s, --skip-install` {#skip-install}

If provided, Docusaurus will not automatically install dependencies after creating the app. The `--package-manager` option is only useful when you are actually installing dependencies.
2 changes: 1 addition & 1 deletion website/docs/api/misc/eslint-plugin/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 0
sidebar_position: 1
id: eslint-plugin
title: '📦 eslint-plugin'
slug: '/api/misc/@docusaurus/eslint-plugin'
Expand Down
4 changes: 2 additions & 2 deletions website/docs/api/misc/logger.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
sidebar_position: 1
sidebar_position: 2
title: '📦 logger'
slug: '/api/plugins/@docusaurus/logger'
slug: '/api/misc/@docusaurus/logger'
---

An encapsulated logger for semantically formatting console messages.
Expand Down
23 changes: 3 additions & 20 deletions website/docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,22 +28,12 @@ Use **[docusaurus.new](https://docusaurus.new)** to test Docusaurus immediately
The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.

```bash
npx create-docusaurus@latest [name] [template]
npx create-docusaurus@latest my-website classic
```

Example:

```bash
npx create-docusaurus@latest website classic
```

If you do not specify `name` or `template`, it will prompt you for them.

We recommend the `classic` template so that you can get started quickly, and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.

The `template` also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory. If it's a git repository, you can also specify a cloning strategy.

You can also use the template's TypeScript variant by passing the `--typescript` flag.
You can also use the template's TypeScript variant by passing the `--typescript` flag. See [TypeScript support](./typescript-support.md) for more information.

```bash
npx create-docusaurus@latest my-website classic --typescript
Expand Down Expand Up @@ -92,14 +82,7 @@ pnpm create docusaurus

</details>

Docusaurus makes best efforts to select a package manager to install dependencies for you, based on the command you are using and the project you are in. You can override this behavior by using `--package-manager [npm/yarn/pnpm]`.

```bash
# Use Yarn to install dependencies even when the command is npx
npx create-docusaurus@latest my-website classic --package-manager yarn
```

Run `npx create-docusaurus@latest --help` for more information about all available flags.
Run `npx create-docusaurus@latest --help`, or check out its [API docs](./api/misc/create-docusaurus.md) for more information about all available flags.

## Project structure {#project-structure}

Expand Down

0 comments on commit 0cc4fa8

Please sign in to comment.