Skip to content
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

docs: improve getting started guide #2710

Merged
merged 2 commits into from
Jul 9, 2021
Merged

docs: improve getting started guide #2710

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
faeb3b0
Clarify some steps in the getting started guide
waldyrious Jan 17, 2021
d2705d3
Getting Started: Complete the Quick Start section
waldyrious Jan 17, 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
36 changes: 29 additions & 7 deletions packages/docs/docs/guide/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
- [Node.js 10+](https://nodejs.org/en/)
- [Yarn Classic](https://classic.yarnpkg.com/en/) (Optional)\*

\* _If your project is using webpack 3.x, you may notice some installation issues with npm. In this case, we recommend using Yarn._
\* _If your project is using webpack 3.x, you may notice some installation issues with `npm`. In this case, we recommend using Yarn._

## Quick Start

The fastest way to get your VuePress project setup is to use our [create-vuepress-site generator](https://github.com/vuepressjs/create-vuepress-site/) which will help scaffold the basic VuePress site structure for you.
The fastest way to get your VuePress project set up is to use our [create-vuepress-site generator](https://github.com/vuepressjs/create-vuepress-site/), which will help scaffold the basic VuePress site structure for you.

To use it, open up your terminal in the desired directory and run the following command:

Expand All @@ -27,19 +27,41 @@ npx create-vuepress-site [optionalDirectoryName]
</code-block>
</code-group>

You will then have the opportunity to configure your VuePress site’s metadata such as:
The command will interactively ask for details to configure your VuePress site’s metadata such as:

- Project Name
- Description
- Maintainer Email
- Maintainer Name
- Repository URL

Once it is complete, you should see your new VuePress site scaffolded in your directory! :tada:
Once this done, a scaffolded documentation site will be created in the `docs` directory (or custom directory name, if passed) under the current directory.

To see it in action, navigate into newly scaffolded directory, install the dependencies and start the local server:

<code-group>
<code-block title="YARN" active>
```bash
cd docs
yarn install
yarn dev
```
</code-block>

<code-block title="NPM">
```bash
cd docs
npm install
npm run dev
```
</code-block>
</code-group>

## Manual Installation

This section will help you build a basic VuePress documentation site from ground up. If you already have an existing project and would like to keep documentation inside the project, start from Step 3.
If you prefer, you can build a basic VuePress documentation site from ground up instead of using the generator mentioned above.

Note: If you already have an existing project and would like to keep documentation inside the project, start from Step 3.

1. Create and change into a new directory

Expand Down Expand Up @@ -85,9 +107,9 @@ This section will help you build a basic VuePress documentation site from ground
mkdir docs && echo '# Hello VuePress' > docs/README.md
```

5. Add some [scripts](https://classic.yarnpkg.com/en/docs/package-json#toc-scripts) to `package.json`
5. Add helper [scripts](https://classic.yarnpkg.com/en/docs/package-json#toc-scripts) to `package.json`

This step is optional but highly recommended, the rest of the documentation will assume those scripts being added.
This step is optional but highly recommended, as the rest of the documentation will assume those scripts being present.

```json
{
Expand Down