Skip to content

docs: improve local setup instructions with prerequisites and troubleshooting #856

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

Open
devacc8 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: improve local setup instructions with prerequisites and troubleshooting #856

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 34 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,37 @@ Base Docs are community-managed. We welcome and encourage contributions from eve

## Local development

Prerequisite: Node.js v19+.
### Prerequisites

Before you begin, ensure you have the following installed:

- **Git** - for cloning the repository
- **Node.js v19+** - required for the Mint CLI

Verify your Node.js version:

```bash
node --version
```

If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/) or use a version manager like [nvm](https://github.com/nvm-sh/nvm).

### Setup steps

1. Clone the repository:

```bash
git clone https://github.com/base/docs.git
cd docs
```

1. Clone the repository.
2. Install the Mint CLI to preview documentation changes locally:

```bash
npm i -g mint
```

3. Preview locally (run from the `docs/` directory where `docs.json` lives):
3. Navigate to the `docs/` directory (where `docs.json` lives) and start the local server:

```bash
cd docs
Expand All @@ -48,13 +69,21 @@ mint dev
Alternatively, without a global install:

```bash
cd docs
npx mint dev
```

4. Open your browser and visit the local URL shown in the terminal (typically `http://localhost:3000`).

### Troubleshooting

- Ensure Node.js v19+ is installed and that you run `mint dev` from the directory containing `docs.json` (usually `docs/`).
- Local preview differs from production: run `mint update` to update the CLI.
| Issue | Solution |
|-------|----------|
| `mint: command not found` | Ensure npm global binaries are in your PATH, or use `npx mint dev` instead |
| `node: command not found` | Install Node.js v19+ from [nodejs.org](https://nodejs.org/) |
| `Error: docs.json not found` | Make sure you run `mint dev` from the `docs/` directory, not the repository root |
| Local preview differs from production | Run `mint update` to update the CLI to the latest version |
| Port already in use | Stop other processes using port 3000, or specify a different port with `mint dev --port 3001` |

## How to contribute

Expand Down