一文掌握GitHub热门开源项目Docusaurus（Kali Linux版）

引言

Docusaurus是Facebook开源的静态网站生成器，特别适合构建文档网站。本文将手把手教你在Kali Linux系统上安装和配置Docusaurus，让你快速搭建专业的文档站点。

准备工作

在开始之前，请确保你的Kali Linux系统满足以下要求：

Kali Linux 2023.x或更新版本
Node.js 16.14或更高版本
npm 8.x或更高版本
Git已安装

1. 更新系统

首先打开终端，更新你的Kali Linux系统：

代码片段

sudo apt update && sudo apt upgrade -y

2. 安装Node.js和npm

Kali Linux默认可能没有安装最新版Node.js，我们需要手动安装：

代码片段

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs

验证安装是否成功：

代码片段

node -v
npm -v

安装Docusaurus

1. 创建项目目录

代码片段

mkdir my-docusaurus && cd my-docusaurus

2. 使用npx初始化Docusaurus项目

代码片段

npx create-docusaurus@latest . classic

这个命令会：
– npx: Node.js包执行工具
– create-docusaurus@latest: 使用最新版Docusaurus创建工具
– .: 在当前目录创建项目
– classic: 使用经典模板（还有blog等其他模板可选）

3. 启动开发服务器

代码片段

npm run start

启动后，默认会在浏览器打开 http://localhost:3000 ，你将看到默认的Docusaurus页面。

Docusaurus项目结构解析

让我们看看自动生成的项目结构：

代码片段

my-docusaurus/
├── blog/                # Markdown格式的博客文章
├── docs/                # Markdown格式的文档内容
├── src/                 
│   ├── components/      # React组件目录
│   ├── css/             # CSS样式文件目录
│   └── pages/           # React页面文件目录
├── static/              # 静态资源目录（图片等）
├── docusaurus.config.js # Docusaurus主配置文件
└── package.json         # Node.js项目配置文件

自定义你的网站

1. 修改配置文件

编辑 docusaurus.config.js:

“`javascript title=”docusaurus.config.js”
module.exports = {
title: ‘我的技术博客’, // 网站标题
tagline: ‘记录与分享技术知识’, // slogan副标题

};

代码片段


### 2. 添加新文档页面

在 `docs`目录下新建Markdown文件：

```markdown title="docs/getting-started.md"
---
id: getting-started    # URL路径标识符（必填）
title: Getting Started # 显示标题（必填）
sidebar_label: Start Here # （可选）侧边栏显示标签 
---

# Getting Started Guide

欢迎使用我们的文档！这是入门指南。

## Section One

这里是第一部分内容...

## Section Two 

这里是第二部分内容...

3. 添加侧边栏配置

编辑 sidebars.js:

“`javascript title=”sidebars.js”
module.exports = {
tutorialSidebar: [
‘getting-started’, //对应docs/getting-started.md文件id

],
};

代码片段


## Kali Linux特有注意事项

1. **权限问题**：Kali默认以root用户运行，建议为开发创建普通用户：
   ```bash 
   adduser devuser && usermod -aG sudo devuser

防火墙设置：如果无法访问3000端口，检查防火墙：
代码片段
```
sudo ufw allow 3000/tcp 
```
性能优化：Kali作为安全测试发行版，默认可能资源占用较高。建议：
代码片段
```
sudo systemctl disable postgresql.service 
sudo systemctl disable redis-server.service 
```

Docker方式运行（可选）

如果你更喜欢容器化方式：

Dockerfile:
“`dockerfile title=”Dockerfile”
FROM node:16-buster-slim

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 3000

CMD [“npm”, “run”, “start”]

代码片段


2. Build and Run:
```bash 
docker build -t docusaurus-site .
docker run -p3000:3000 docusaurus-site

GitHub Pages部署指南

Install gh-pages:

代码片段

npm install --save gh-pages

Add to package.json:
“`json title=”package.json” {5,6}
{
“scripts”: {
“start”: “docusaurus start”,
“build”: “docusaurus build”,
“deploy”: “GITUSER= USESSH=true npm run deploy”,
}
}

代码片段


3. Deploy:
```bash 
npm run deploy

Troubleshooting常见问题解决

问题1: Error: EACCES: permission denied

解决方案：

代码片段

sudo chown -R $(whoami) ~/.npm  
sudo chown -R $(whoami) node_modules

问题2: Node.js版本过低

解决方案：

代码片段

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash  
nvm install --lts  
nvm use --lts

问题3: Port already in use

解决方案：

代码片段

lsof -i :3000  
kill -9 <PID>

或者直接修改端口：
javascript title="docket.config.js" {5} module.exports = { server: { port:4000 } }

Final Thoughts总结

通过本文你学会了：

✅ Kali Linux环境下配置Node.js开发环境
✅ Docusarurus项目的创建与初始化
✅ Markdown文档编写与侧边栏配置
✅ Kali特有问题的解决方案
✅ Docker容器化部署方案
✅ GitHub Pages自动化部署

下一步建议：

🔹 官方文档深入学习高级功能
🔹 GitHub仓库提交PR参与贡献
🔹 社区Discord获取实时帮助

Happy Documenting! 🚀