iOS设备用户必看：GitHub明星项目Docusaurus详解

引言

作为iOS设备用户，你可能经常需要查阅技术文档或搭建个人博客。今天我要介绍的Docusaurus是Meta（原Facebook）开源的一个静态网站生成器，专门为构建文档网站而设计。它简单易用、支持Markdown、内置搜索功能，并且完全响应式——这意味着在iPhone和iPad上都能完美显示！

准备工作

在开始之前，请确保你的iOS设备已准备好：

1. 安装Termux（App Store搜索安装）：这是一个强大的终端模拟器，让我们能在iOS上运行Linux命令
2. 安装iSH Shell（备用方案）：另一个iOS上的Linux环境
3. 基础命令行知识：了解cd、ls等基本命令

💡 注意：由于iOS的限制，Termux需要从App Store下载，部分功能可能受限。建议在Mac上开发完成后部署到GitHub Pages。

第一步：安装Node.js环境

Docusaurus基于Node.js，我们需要先在Termux中安装Node环境：

# 更新软件包列表
pkg update

# 安装Node.js和npm
pkg install nodejs

# 验证安装是否成功
node --version
npm --version

如果遇到权限问题，可以尝试：

# 清除npm缓存
npm cache clean --force

# 修改npm全局安装目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

第二步：创建Docusaurus项目

在Termux中执行以下命令：

# 创建一个新目录并进入
mkdir my-docusaurus && cd my-docusaurus

# 使用npx初始化Docusaurus项目
npx create-docusaurus@latest . classic

# 启动开发服务器（端口可能受限）
npm run start

⚠️ iOS设备限制：由于iOS的网络限制，开发服务器可能无法直接在移动浏览器中访问。建议：
– 使用npm run build构建静态文件后查看
– 或者将项目推送到GitHub后通过GitHub Pages查看效果

第三步：项目结构解析

让我们看看生成的目录结构（在Termux中使用ls查看）：

my-docusaurus/
├── blog/                # 博客Markdown文件存放处
│   ├── first-blog.md    # 示例博客文章
├── docs/                # 文档Markdown文件存放处
│   ├── intro.md         # 示例文档
├── src/                 # React组件源文件
│   ├── css/             # 自定义CSS样式
│   └── pages/           # 额外页面组件
├── static/              # 静态资源目录（图片等）
├── docusaurus.config.js # Docusaurus主配置文件
└── package.json         # Node.js项目配置文件

第四步：自定义你的网站

1. 修改配置文件

用Termux内置的nano编辑器修改配置：

nano docusaurus.config.js

找到以下部分进行修改：

“`javascript title=”docusaurus.config.js”
module.exports = {
title: ‘我的技术博客’, // ←修改这里作为网站标题
tagline: ‘记录学习点滴’, // ←修改副标题

};

保存退出：按`Ctrl+O`回车，然后`Ctrl+X`

### 2. 添加一篇新博客

# Termux中创建新博客文章（替换日期和标题）
npx docusaurus write-translations zh-Hans 
npx docusaurus write-translations en 
echo '---
title: "我的第一篇博客"
date: "2023-07-20"
description: "这是我的第一篇Docusaurus博客"
---' > blog/2023-07-20-first-post.md 

然后在文件中继续添加你的Markdown内容。

iOS设备上的实用技巧

1. 使用Working Copy应用：这是一个优秀的Git客户端，可以方便地管理你的Docusaurus项目仓库

2. Markdown编辑推荐：

   • iA Writer：优秀的Markdown编辑器
   • Bear：美观的笔记应用支持Markdown导出

3. 图片处理：
   “`markdown title=”blog/post.md”

   将图片放入static/img/目录下即可引用 

4. **同步开发**：
   建议在iOS设备上写作内容(Markdown文件)，然后在Mac或PC上进行构建和部署 

## GitHub Pages部署指南（从iOS完成）

1. **初始化Git仓库**：
   ```bash 
   git init 
   git add . 
   git commit -m "初始提交" 

1. 创建GitHub仓库：
   在Safari中访问GitHub.com新建仓库

2. 添加远程并推送：

   代码片段 复制代码

   git remote add origin https://github.com/用户名/仓库名.git 
   git push -u origin main 
   

3. 启用GitHub Pages：
   在GitHub仓库Settings > Pages中：

   • Source选择gh-pages分支或main分支/docs文件夹
   • Save后等待几分钟即可访问

Docusaurus的特色功能体验

1. 暗黑模式：自动跟随系统设置或在右上角切换

2. 文档版本控制：
   bash title="创建新版本"
npm run docusaurus docs:version v1.0


3. 多语言支持：
   修改docusaurus.config.js中的i18n配置

4. Algolia搜索集成（需API key）：
   提供专业的文档搜索体验

iOS用户常见问题解决

❌ 问题1: Termux中无法启动开发服务器
✅ 解决方案: iOS限制导致无法绑定端口。改用build后查看静态文件或使用外部设备测试

❌ 问题2: npm install卡住
✅ 解决方案: Termux资源有限。尝试:

npm install --verbose #查看进度  
或者  
CI=true npm install #简化安装过程  

❌ 问题3: Git push失败
✅ 解决方案: iOS上SSH配置复杂。改用HTTPS方式并在钥匙串保存凭据

❌ 问题4: Markdown中文显示异常
✅ 解决方案: Termux默认locale设置问题:

export LANG=en_US.UTF-8  
export LC_ALL=en_US.UTF-8  

Docusaurus vs iOS其他方案对比

Docusaurus模板推荐（适合iOS用户）

1. 技术文档模板 (官方经典版)
2. 个人博客主题 (专注写作)
3. 产品文档主题 (商业化风格)

导入方法:
“`bash title=”使用模板”
git clone https://github.com/template-repo.git my-site
cd my-site && npm install

## D2C (Docs to Code)工作流优化建议

对于需要在iPad Pro上完成写作+发布的开发者:

1. ✍🏻 *写作阶段*: iPad + Magic Keyboard + iA Writer/Bear应用   
2. 🛠 *开发阶段*: MacBook Pro本地运行调试   
3. ☁ *部署阶段*: GitHub Actions自动化构建发布   
4. 📱 *移动端检查*: iPhone/iPad访问生产环境确认效果   

这种工作流结合了移动设备的便携性和桌面设备的强大功能。

## Docusauru移动端优化技巧

确保你的网站在iPhone/iPad上有最佳表现:

1. `docusaurus.config.js`中添加响应式meta标签:
```javascript title="配置响应式视图" 
module.exports = {
+ headTags: [
+     {
+       tagName: 'meta',
+       attributes: {
+         name: 'viewport',
+         content: 'width=device-width, initial-scale=1, shrink-to-fit=no',
+       },
+     },
+ ],
};

1. CSS媒体查询优化小屏显示:
   “`css title=”src/css/custom.css”
   @media (max-width: 768px) {
   :root {
   –ifm-font-size-base:15px;
   }
   .navbar__items { flex-direction: column; }
   }

3. Swipeable移动端手势支持:
```bash title="安装插件" 
npm install @docusaurus/plugin-ideal-image @docrusauruseffect-carousel --save  

GitHub Actions自动化部署（全移动端完成）

在你的项目中创建.github/workflows/deploy.yml:

“`yaml title=”deploy.yml”
name: Deploy to GitHub Pages

on:
push:
branches:[main]

jobs:
deploy:
runs-on: ubuntu-latest

steps:
– uses: actions/checkout@v2

• uses: actions/setup-node@v2

• run: npm ci && npm run build

• uses: peaceiris/actions-gh-pages@v3
  with:
  githubtoken:${{ secrets.GITHUBTOKEN }}
  publish_dir:/build/

这样每次git push后都会自动构建并部署到gh-pages分支！

## Markdown增强技巧（适合移动端编辑）

Docusauru扩展了标准Markdown语法:

````markdown title="代码块分组展示"
```jsx twoslash {1,3} title="React示例"
function Counter() {
 const [count, setCount] = useState(0)
 return <button onClick={() => setCount(c=>c+1)}>{count}</button>
}

““

效果展示组内代码高亮指定行！

表格优化写法:

“`markdown title=”简化表格语法”

这种语法在手机小屏上更容易编辑维护。

## Tailwind CSS集成方案（可选）

如果你熟悉Tailwind，可以轻松集成:

1️⃣ First install tailwindcss:

```bash terminal=true icon=command-line color=blue animation=glow $ npm install tailwindcss postcss autoprefixer --save-dev $ npx tailwindcss init

2️⃣ Create postcss.config.js:

javascript filename="/postcss.config.js" const tailwind = require('tailwindcss'); module.exports = { plugins:[tailwind('./tailwind.config.js'),require('autoprefixer')], };

Now you can use Tailwind classes in your CSS!

这种配置让你的文档UI更加现代化。

希望这篇指南能帮助你在iOS设备上轻松使用Dousaurs！无论是通勤路上用iPhone写技术博客，还是用iPad Pro整理项目文档，这个强大的工具都能完美胜任。

如果有任何问题欢迎留言讨论！Happy documenting! 📱💻