Installation

Initial Installation Guide — Astro Docus

Welcome! This guide walks you through everything from scratch — even if you have never touched code before. By the end, you will have the Astro Docus project running on your own computer.

---

Before You Start — Understand What You Are Installing

Before touching anything, here is what each tool does in plain English:

• Node.js — The engine that runs JavaScript outside the browser. Astro runs on top of it.
• npm — The package manager that comes free with Node.js. Used to install project libraries.
• VS Code — The editor where you write and edit code.
• Git — A “save point” system for your files (version control). Optional for now.
• Notepad++ — A lightweight alternative text editor.

---

Download Checklist

Tool	Required?	Official Link
Node.js (LTS)	Required	https://nodejs.org
VS Code	Required	https://code.visualstudio.com
Notepad++	Optional	https://notepad-plus-plus.org
Git	Recommended	https://git-scm.com

Note: Notepad++ is a fallback if VS Code feels too heavy. For Astro projects, VS Code is far more comfortable.

---

Step 1 — Install Node.js

Node.js is the foundation. Without it, the Astro project cannot run.

1.1 Download Node.js

1. Open your browser and go to: https://nodejs.org
2. You will see two big buttons:
   • Left: LTS (Long Term Support) — CHOOSE THIS
   • Right: Current (newest, but sometimes unstable)
3. Click the LTS button.

Why LTS? It is more stable and production-ready. Current has the latest features but is riskier for beginners.

Current Node.js LTS is around v22.x. The downloaded file will look like: node-v22.x.x-x64.msi

1.2 Install Node.js

1. Double-click the .msi file you downloaded.
2. The installer wizard appears — click Next.
3. Check “I accept the terms in the License Agreement” → Next.
4. Destination Folder: leave default (C:\Program Files\nodejs\) → Next.
5. Custom Setup: leave default → Next.
6. Tools for Native Modules: DO NOT check (not needed for beginners) → Next.
7. Click Install → wait → click Finish.

1.3 Verify Node.js

This is the most important step — to confirm the install worked.

1. Open Command Prompt (CMD) or PowerShell
   • Press Win + R → type cmd → Enter
2. Type this command:

node --version

3. If you see a version like v22.14.0, it WORKED.
4. Check npm too:

npm --version

5. If you see something like 10.9.2, npm was installed automatically.

If it errors? Close CMD, reopen it. If it still errors, restart your computer.

---

Step 2 — Install VS Code

VS Code is where you write and edit code. It is the most comfortable editor for Astro projects.

2.1 Download VS Code

1. Go to: https://code.visualstudio.com
2. The site auto-detects your OS. Click Download for Windows.
3. Downloaded file: VSCodeUserSetup-x64-1.xx.x.exe

2.2 Install VS Code

1. Double-click the installer.
2. Check “I accept the agreement” → Next.
3. Select Additional Tasks: check everything related to “Add to PATH” and “Create a desktop icon” → Next.
4. Click Install → wait → Finish.

Why VS Code? It has built-in support for JavaScript, TypeScript, and Node.js. There are also Astro/Starlight extensions that make coding much easier.

---

Step 3 — Install Git (Optional but Recommended)

Git is version control — like “save points” in a game. If you mess up an edit, you can roll back to a previous version.

3.1 Download Git

1. Go to: https://git-scm.com
2. Click Download for Windows (auto-detects 64-bit).
3. File: Git-2.xx.x-64-bit.exe

3.2 Install Git

1. Double-click the installer.
2. Next → Next → Next (all defaults are fine).
3. Adjusting your PATH environment: choose “Git from the command line and also from 3rd-party software” — IMPORTANT.
4. Leave the rest as default → Install → Finish.

3.3 Verify Git

git --version

If you see git version 2.xx.x, it worked.

---

Step 4 — Notepad++ (Lightweight Alternative)

If you do not want to install VS Code or your PC is low-spec, Notepad++ is an alternative.

4.1 Download & Install Notepad++

1. Go to: https://notepad-plus-plus.org
2. Click Download → pick the latest version (x64).
3. Double-click the installer.
4. Choose your language → OK.
5. Next → I accept → Next → Next → Install → Finish.

Recommendation: Skip this if you already have VS Code. Notepad++ is better for quickly editing small files or opening logs.

---

Step 5 — Run the Astro Docus Project

Now that you have all the tools, let’s run the project.

5.1 Open the Project Folder in VS Code

1. Open VS Code.
2. Click File → Open Folder.
3. Select your Astro Docus project folder (the one containing astro.config.mjs).
4. Click Select Folder.

5.2 Open the Terminal in VS Code

1. In VS Code, press Ctrl + (backtick), or
2. Click Terminal → New Terminal.

The terminal appears at the bottom of VS Code.

5.3 Install Dependencies

This step downloads all the libraries the project needs.

In the terminal, type:

npm install

Or if the project uses pnpm (check for a pnpm-lock.yaml file):

pnpm install

Wait until it finishes. Once the node_modules folder appears, it worked.

What are dependencies? Libraries the project needs — Astro, Starlight, Cloudflare adapter, etc. They are all listed in package.json.

5.4 Start the Development Server

Once installation is complete, type:

npm run dev

Or:

pnpm dev

If successful, you will see output like:

  🚀  astro  v4.x.x started in 123ms

  ┃ Local    http://localhost:4321/
  ┃ Network  use --host to expose

5.5 Open in Browser

1. Open your browser (Chrome, Firefox, Edge).
2. Go to: http://localhost:4321
3. BOOM! Your Astro Docus documentation is live.

---

Project Structure (So You Do Not Get Lost)

Once you open the project, you will see many files. Here is a rough map:

├── astro.config.mjs      ← MAIN FILE (project brain)
├── package.json          ← dependencies list
├── public/               ← static files (favicon, images, etc.)
├── src/
│   ├── assets/           ← images & icons
│   ├── content/docs/     ← ALL YOUR DOCUMENTATION GOES HERE
│   ├── data/             ← JSON files for dynamic content
│   ├── styles/           ← CSS files
│   └── widget/           ← Astro components (Header, Footer, etc.)

Files you will edit most often:

• src/content/docs/ → write new documentation
• astro.config.mjs → change title, sidebar, logo
• src/styles/ → change appearance

---

Quick Troubleshooting

Problem	Solution
node command not found	Close CMD/terminal, reopen. Or restart your computer.
npm install fails	Check internet. Try npm cache clean --force then retry.
Port 4321 already in use	Run npm run dev -- --port 3000.
VS Code cannot open folder	Ensure folder permissions. Try running VS Code as Administrator.

---

Quick Summary

1. Install Node.js LTS       → nodejs.org
2. Install VS Code           → code.visualstudio.com
3. Install Git (optional)    → git-scm.com
4. Open project in VS Code
5. Terminal: npm install
6. Terminal: npm run dev
7. Browser: localhost:4321

---

If you can open localhost:4321 in your browser, you have cleared the hardest part. Everything from here is just editing content and styling.

Ready to move on to Part 2: Writing Your First Documentation?