diff --git a/website/docs/api/misc/create-docusaurus.md b/website/docs/api/misc/create-docusaurus.md new file mode 100644 index 000000000000..e35d3884cd78 --- /dev/null +++ b/website/docs/api/misc/create-docusaurus.md @@ -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. diff --git a/website/docs/api/misc/eslint-plugin/README.md b/website/docs/api/misc/eslint-plugin/README.md index 3354d63f8029..8519bcfe6ef1 100644 --- a/website/docs/api/misc/eslint-plugin/README.md +++ b/website/docs/api/misc/eslint-plugin/README.md @@ -1,5 +1,5 @@ --- -sidebar_position: 0 +sidebar_position: 1 id: eslint-plugin title: '📦 eslint-plugin' slug: '/api/misc/@docusaurus/eslint-plugin' diff --git a/website/docs/api/misc/logger.md b/website/docs/api/misc/logger.md index 290bc762c01e..986c4d2880da 100644 --- a/website/docs/api/misc/logger.md +++ b/website/docs/api/misc/logger.md @@ -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. diff --git a/website/docs/installation.md b/website/docs/installation.md index a7aa1fa08c81..26b701b98b85 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -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 @@ -92,14 +82,7 @@ pnpm create docusaurus -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}