1259 lines
25 KiB
Markdown
1259 lines
25 KiB
Markdown
# MkDocs 是什么
|
||
|
||
##
|
||
|
||
**MkDocs** 是一个**快速、简单、优雅的静态网站生成器**，专门用于从 Markdown 文件构建项目文档。它的设计目标非常明确：让创建美观、实用的文档网站变得尽可能轻松。
|
||
|
||
### 核心特点
|
||
|
||
**1. 极简配置**
|
||
|
||
- 只需一个 YAML 配置文件 (`mkdocs.yml`)
|
||
|
||
- 几分钟内即可搭建起完整的文档站点
|
||
|
||
**2. Markdown 驱动**
|
||
|
||
- 所有内容都使用 Markdown 编写
|
||
|
||
- 对开发者友好，学习成本低
|
||
|
||
**3. 丰富的主题系统**
|
||
|
||
- 内置多个主题（如 `material`、`readthedocs`）
|
||
|
||
- Material for MkDocs 主题尤为强大，支持：
|
||
|
||
- 响应式设计
|
||
|
||
- 深色/浅色模式
|
||
|
||
- 搜索功能
|
||
|
||
- 多级导航
|
||
|
||
- 代码高亮
|
||
|
||
### 在你的 DevOps 平台中的角色
|
||
|
||
在你的“个人超级 DevOps 平台”中，**MkDocs 作为个人知识库**：
|
||
|
||
text
|
||
|
||
# 典型结构
|
||
|
||
docs/ # 你的知识库
|
||
├── index.md # 首页
|
||
├── devops-platform.md # DevOps平台搭建记录
|
||
├── kubernetes-guide.md # K8s学习笔记
|
||
├── api-references/ # API文档
|
||
└── troubleshooting.md # 排错手册
|
||
mkdocs.yml # 配置文件
|
||
|
||
### 为什么适合你的技术栈？
|
||
|
||
**与你的其他组件完美集成：**
|
||
|
||
1. **与 Gitea 结合**
|
||
|
||
- 将 MkDocs 源码存储在 Gitea 中
|
||
|
||
- 使用 Git Hook 自动构建和部署文档
|
||
|
||
- 用 Gitea 的 Wiki 做协作，MkDocs 做正式知识库
|
||
|
||
2. **与 MinIO 结合**
|
||
|
||
- 将构建的静态文档网站托管到 MinIO
|
||
|
||
- 使用 MinIO 作为文档附件存储
|
||
|
||
3. **作为知识沉淀中心**
|
||
|
||
- 记录你的 DevOps 平台搭建过程
|
||
|
||
- 编写团队技术规范
|
||
|
||
- 整理问题解决方案
|
||
|
||
### 快速示例
|
||
|
||
**安装：**
|
||
|
||
bash
|
||
|
||
pip install mkdocs mkdocs-material
|
||
|
||
**创建新站点：**
|
||
|
||
bash
|
||
|
||
mkdocs new my-knowledge-base
|
||
cd my-knowledge-base
|
||
|
||
**简单配置 (`mkdocs.yml`)：**
|
||
|
||
yaml
|
||
|
||
site_name: 我的技术知识库
|
||
theme:
|
||
name: material
|
||
features:
|
||
- navigation.tabs
|
||
- navigation.sections
|
||
- search.suggest
|
||
- search.highlight
|
||
|
||
nav:
|
||
|
||
- 首页: index.md
|
||
- DevOps平台:
|
||
- 架构设计: devops/architecture.md
|
||
- 部署指南: devops/deployment.md
|
||
- 移动开发:
|
||
- CI/CD流程: mobile/ci-cd.md
|
||
- 发布管理: mobile/release.md
|
||
|
||
**编写内容 (`docs/index.md`)：**
|
||
|
||
markdown
|
||
|
||
# 欢迎来到我的知识库
|
||
|
||
这里是个人超级 DevOps 平台的所有技术文档。
|
||
|
||
## 平台组件
|
||
|
||
- **代码管理**: Gitea
|
||
- **依赖管理**: Nexus
|
||
- **文档管理**: MkDocs
|
||
- **监控告警**: Sentry + Grafana
|
||
|
||
**本地预览：**
|
||
|
||
bash
|
||
|
||
mkdocs serve
|
||
|
||
# 在 http://localhost:8000 查看
|
||
|
||
### 进阶用法
|
||
|
||
**版本化文档：**
|
||
|
||
yaml
|
||
|
||
theme:
|
||
name: material
|
||
features:
|
||
- navigation.tabs
|
||
- navigation.tabs.sticky
|
||
language: zh
|
||
|
||
extra:
|
||
version:
|
||
provider: mike
|
||
|
||
plugins:
|
||
|
||
- search
|
||
- mike:
|
||
alias_type: symlink
|
||
|
||
**与 CI/CD 集成：**
|
||
|
||
yaml
|
||
|
||
# GitLab CI 示例
|
||
|
||
pages:
|
||
stage: deploy
|
||
script:
|
||
- pip install mkdocs mkdocs-material
|
||
- mkdocs build
|
||
- mv site public
|
||
artifacts:
|
||
paths:
|
||
- public
|
||
only:
|
||
- main
|
||
|
||
### 优势总结
|
||
|
||
✅ **简单易用** - Markdown 编写，配置简单
|
||
✅ **维护方便** - 版本控制友好
|
||
✅ **部署灵活** - 生成静态文件，可托管到任何地方
|
||
✅ **搜索强大** - 内置全文搜索
|
||
✅ **移动友好** - 响应式设计
|
||
✅ **社区活跃** - 丰富的插件生态
|
||
|
||
在你的 DevOps 生态中，MkDocs 是**文档即代码**理念的完美实践，它让技术文档的编写、维护和发布变得和写代码一样规范高效。
|
||
|
||
vscode下载
|
||
|
||
我来详细介绍如何下载和安装 Visual Studio Code (VSCode)，这是开发者必备的代码编辑器。
|
||
|
||
## 下载 VSCode 的几种方式
|
||
|
||
### 1. **官方网站下载**（最推荐）
|
||
|
||
**访问官网：** [https://code.visualstudio.com/](https://code.visualstudio.com/)
|
||
|
||
官网会自动检测你的操作系统，推荐合适的版本：
|
||
|
||
- **Windows 用户**：下载 `.exe` 安装包
|
||
|
||
- **macOS 用户**：下载 `.dmg` 文件或 `.zip` 压缩包
|
||
|
||
- **Linux 用户**：提供多种包格式（`.deb`, `.rpm`, `.tar.gz`）
|
||
|
||
### 2. **各平台具体下载地址**
|
||
|
||
**Windows：**
|
||
|
||
text
|
||
|
||
https://code.visualstudio.com/sha/download?build=stable&os=win32-x64-user
|
||
|
||
**macOS：**
|
||
|
||
- Intel 芯片：
|
||
|
||
text
|
||
|
||
https://code.visualstudio.com/sha/download?build=stable&os=darwin
|
||
|
||
- Apple Silicon (M1/M2/M3)：
|
||
|
||
text
|
||
|
||
https://code.visualstudio.com/sha/download?build=stable&os=darwin-arm64
|
||
|
||
**Linux：**
|
||
|
||
text
|
||
|
||
https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64
|
||
|
||
### 3. **使用包管理器安装**
|
||
|
||
**Windows (Winget)：**
|
||
|
||
bash
|
||
|
||
winget install Microsoft.VisualStudioCode
|
||
|
||
**macOS (Homebrew)：**
|
||
|
||
bash
|
||
|
||
brew install --cask visual-studio-code
|
||
|
||
**Ubuntu/Debian：**
|
||
|
||
bash
|
||
|
||
sudo apt update
|
||
sudo apt install software-properties-common apt-transport-https wget
|
||
wget -q https://packages.microsoft.com/keys/microsoft.asc -O- | sudo apt-key add -
|
||
sudo add-apt-repository "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main"
|
||
sudo apt update
|
||
sudo apt install code
|
||
|
||
**CentOS/RHEL/Fedora：**
|
||
|
||
bash
|
||
|
||
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
|
||
sudo sh -c 'echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/yum.repos.d/vscode.repo'
|
||
sudo dnf install code # 或 sudo yum install code
|
||
|
||
### 4. **便携版下载**
|
||
|
||
如果你想要免安装版本：
|
||
|
||
- **Windows**：下载 `VSCode-win32-x64-XX.X.X.zip`
|
||
|
||
- **macOS**：下载 `VSCode-darwin-x64-XX.X.X.zip`
|
||
|
||
- **Linux**：下载 `VSCode-linux-x64-XX.X.X.tar.gz`
|
||
|
||
## 安装步骤
|
||
|
||
### **Windows 安装**
|
||
|
||
1. 下载 `.exe` 安装包
|
||
|
||
2. 双击运行安装程序
|
||
|
||
3. 同意许可协议
|
||
|
||
4. 选择安装选项（推荐勾选）：
|
||
|
||
- ✅ 将“通过 Code 打开”操作添加到 Windows 资源管理器文件上下文菜单
|
||
|
||
- ✅ 将“通过 Code 打开”操作添加到 Windows 资源管理器目录上下文菜单
|
||
|
||
- ✅ 将 Code 注册为受支持的文件类型的编辑器
|
||
|
||
- ✅ 添加到 PATH（允许从命令行运行 `code`）
|
||
|
||
### **macOS 安装**
|
||
|
||
1. 下载 `.dmg` 文件
|
||
|
||
2. 双击打开磁盘映像
|
||
|
||
3. 将 VSCode 图标拖到“应用程序”文件夹
|
||
|
||
4. 首次运行时，可能会提示“无法打开”，需要：
|
||
|
||
- 右键点击 VSCode → 打开
|
||
|
||
- 或在“系统偏好设置 → 安全性与隐私”中允许打开
|
||
|
||
### **Linux 安装**
|
||
|
||
**使用 .deb 包 (Ubuntu/Debian)：**
|
||
|
||
bash
|
||
|
||
sudo dpkg -i code_*.deb
|
||
sudo apt-get install -f # 安装依赖
|
||
|
||
## 首次设置建议
|
||
|
||
安装完成后，建议进行以下配置：
|
||
|
||
### 1. **安装中文语言包**
|
||
|
||
1. 打开 VSCode
|
||
|
||
2. 按 `Ctrl+Shift+X` 打开扩展面板
|
||
|
||
3. 搜索 `Chinese (Simplified)`
|
||
|
||
4. 点击安装并重启
|
||
|
||
### 2. **推荐扩展**（根据你的 DevOps 需求）
|
||
|
||
**通用开发：**
|
||
|
||
- `GitLens` - Git 增强
|
||
|
||
- `Git History` - Git 历史查看
|
||
|
||
- `Error Lens` - 错误提示增强
|
||
|
||
- `Path Intellisense` - 路径自动补全
|
||
|
||
**DevOps 相关：**
|
||
|
||
- `Docker` - Docker 支持
|
||
|
||
- `Kubernetes` - K8s 支持
|
||
|
||
- `YAML` - YAML 语言支持
|
||
|
||
- `HashiCorp Terraform` - Terraform 支持
|
||
|
||
**文档编写：**
|
||
|
||
- `Markdown All in One` - Markdown 增强
|
||
|
||
- `markdownlint` - Markdown 格式检查
|
||
|
||
- `Paste Image` - 粘贴图片到 Markdown
|
||
|
||
**你的技术栈扩展：**
|
||
|
||
- `Gradle for Java` - Gradle 支持
|
||
|
||
- `MinIO` - MinIO 文件管理
|
||
|
||
- `Gitea` - Gitea 集成
|
||
|
||
### 3. **常用配置**
|
||
|
||
json
|
||
|
||
// settings.json
|
||
{
|
||
"editor.fontSize": 14,
|
||
"editor.tabSize": 2,
|
||
"editor.formatOnSave": true,
|
||
"editor.codeActionsOnSave": {
|
||
"source.fixAll": "explicit"
|
||
},
|
||
"files.autoSave": "afterDelay",
|
||
"terminal.integrated.defaultProfile.windows": "Git Bash",
|
||
"workbench.colorTheme": "Default Dark Modern",
|
||
"workbench.iconTheme": "material-icon-theme"
|
||
}
|
||
|
||
## 便携版使用（无需安装）
|
||
|
||
如果你下载的是便携版：
|
||
|
||
**Windows：**
|
||
|
||
1. 解压 `VSCode-win32-x64-XX.X.X.zip` 到任意目录
|
||
|
||
2. 运行 `Code.exe`
|
||
|
||
**macOS/Linux：**
|
||
|
||
1. 解压压缩包
|
||
|
||
2. 进入解压目录，运行 `./Code`（可能需要 `chmod +x`）
|
||
|
||
## 验证安装
|
||
|
||
打开终端/命令提示符，输入：
|
||
|
||
bash
|
||
|
||
code --version
|
||
|
||
# 或
|
||
|
||
code --help
|
||
|
||
如果正确安装，会显示版本信息：
|
||
|
||
text
|
||
|
||
1.84.2
|
||
...
|
||
|
||
## 小贴士
|
||
|
||
1. **自动更新**：VSCode 默认启用自动更新，可以在设置中调整
|
||
|
||
2. **Insiders 版本**：如果想体验最新功能，可以下载 [VSCode Insiders](https://code.visualstudio.com/insiders/)
|
||
|
||
3. **同步设置**：登录 Microsoft/GitHub 账号可同步设置到不同设备
|
||
|
||
4. **命令行使用**：安装时添加到 PATH 后，可以在终端中用 `code .` 打开当前目录
|
||
|
||
## 快速开始
|
||
|
||
安装完成后，你可以：
|
||
|
||
1. 按 `F1` 或 `Ctrl+Shift+P` 打开命令面板
|
||
|
||
2. 输入 `>Git: Clone` 克隆你的 Gitea 仓库
|
||
|
||
3. 开始编写你的 DevOps 平台代码和文档
|
||
|
||
VSCode 是搭建和维护你的“个人超级 DevOps 平台”的绝佳工具，配合你提到的 Gitea、MkDocs 等组件，能极大提升开发效率！
|
||
|
||
- **Typora**（所见即所得）
|
||
下载
|
||
|
||
# Typora 下载和安装指南
|
||
|
||
## 官方下载渠道
|
||
|
||
### 1. **官方网站**
|
||
|
||
**访问：** [https://typora.io/](https://typora.io/)
|
||
|
||
点击首页的 "Download" 按钮，会自动推荐适合你系统的版本。
|
||
|
||
### 2. **各平台直接下载链接**
|
||
|
||
**Windows：**
|
||
|
||
- 64位：https://typora.io/windows/typora-setup-x64.exe
|
||
|
||
- 32位：https://typora.io/windows/typora-setup-ia32.exe
|
||
|
||
**macOS：**
|
||
|
||
- Intel：https://typora.io/mac/Typora.dmg
|
||
|
||
- Apple Silicon (M1/M2/M3)：https://typora.io/mac/Typora.dmg （通用版本）
|
||
|
||
**Linux：**
|
||
|
||
bash
|
||
|
||
# Debian/Ubuntu
|
||
|
||
wget -qO - https://typora.io/linux/public-key.asc | sudo tee /etc/apt/trusted.gpg.d/typora.asc
|
||
sudo add-apt-repository 'deb https://typora.io/linux ./'
|
||
sudo apt update
|
||
sudo apt install typora
|
||
|
||
# 或直接下载 .deb 包
|
||
|
||
https://typora.io/linux/Typora-linux-x64.deb
|
||
|
||
### 3. **国内镜像/备用下载**
|
||
|
||
由于网络原因，如果官网下载慢，可以尝试：
|
||
|
||
**GitHub Releases：**
|
||
|
||
text
|
||
|
||
https://github.com/typora/typora-issues/releases
|
||
|
||
**第三方镜像站：**
|
||
|
||
- 腾讯软件中心：https://pc.qq.com/detail/10/detail_22850.html
|
||
|
||
- 华为云镜像：https://mirrors.huaweicloud.com/typora/
|
||
|
||
## 安装步骤
|
||
|
||
### **Windows 安装**
|
||
|
||
1. 下载 `.exe` 安装包
|
||
|
||
2. 双击运行安装程序
|
||
|
||
3. 选择安装位置（默认 `C:\Program Files\Typora`）
|
||
|
||
4. 创建桌面快捷方式和开始菜单项
|
||
|
||
5. 完成安装
|
||
|
||
### **macOS 安装**
|
||
|
||
1. 下载 `.dmg` 文件
|
||
|
||
2. 双击打开磁盘映像
|
||
|
||
3. 将 Typora 图标拖到 "应用程序" 文件夹
|
||
|
||
4. 首次运行时，如果提示 "无法打开"：
|
||
|
||
- 右键点击 Typora → 打开
|
||
|
||
- 或进入 "系统偏好设置 → 安全性与隐私" → 点击 "仍要打开"
|
||
|
||
### **Linux 安装**
|
||
|
||
bash
|
||
|
||
# 使用 .deb 包安装
|
||
|
||
sudo dpkg -i Typora-linux-x64.deb
|
||
sudo apt install -f # 修复依赖
|
||
|
||
# 或使用 Snap
|
||
|
||
sudo snap install typora
|
||
|
||
## 许可证激活
|
||
|
||
**注意：Typora 现在是付费软件**（从 2021.11 开始）
|
||
|
||
### 1. **试用版**
|
||
|
||
- 提供 15 天免费试用
|
||
|
||
- 试用期满后需要购买许可证
|
||
|
||
### 2. **购买许可证**
|
||
|
||
1. 访问：[https://store.typora.io/](https://store.typora.io/)
|
||
|
||
2. 选择许可证类型：
|
||
|
||
- **个人版**：$14.99（3台设备）
|
||
|
||
- **商业版**：$29.99（3台设备）
|
||
|
||
- **教育优惠**：有折扣
|
||
|
||
3. 购买后会收到许可证密钥
|
||
|
||
### 3. **激活步骤**
|
||
|
||
1. 打开 Typora
|
||
|
||
2. 菜单栏选择 `帮助 → 我的许可证...`
|
||
|
||
3. 输入邮箱和许可证密钥
|
||
|
||
4. 激活成功
|
||
|
||
## 替代方案（如果你不想付费）
|
||
|
||
### **免费开源替代品**
|
||
|
||
1. **MarkText** - 类似 Typora 的免费开源编辑器
|
||
|
||
- GitHub：[GitHub - marktext/marktext: 📝A simple and elegant markdown editor, available for Linux, macOS and Windows.](https://github.com/marktext/marktext)
|
||
|
||
- 下载：[Releases · marktext/marktext · GitHub](https://github.com/marktext/marktext/releases)
|
||
|
||
2. **Obsidian** - 强大的知识库工具，免费个人使用
|
||
|
||
- 官网：[https://obsidian.md/](https://obsidian.md/)
|
||
|
||
3. **Zettlr** - 学术写作的 Markdown 编辑器
|
||
|
||
- 官网：[https://www.zettlr.com/](https://www.zettlr.com/)
|
||
|
||
4. **VSCode + Markdown 扩展**
|
||
|
||
bash
|
||
|
||
# 安装以下扩展
|
||
|
||
1. Markdown All in One
|
||
2. Markdown Preview Enhanced
|
||
3. Markdown Preview Github Styling
|
||
|
||
### **旧版本 Typora**
|
||
|
||
如果你有旧版本 (v0.11.18 及之前)，可以继续使用：
|
||
|
||
- GitHub 旧版本下载：https://github.com/typora/typora-issues/issues/8102
|
||
|
||
- **注意**：旧版本可能存在安全漏洞
|
||
|
||
## Typora 基本使用
|
||
|
||
### 1. **界面概览**
|
||
|
||
text
|
||
|
||
左侧：文件树或大纲视图
|
||
中间：编辑区域（所见即所得）
|
||
右侧：大纲导航
|
||
|
||
### 2. **常用快捷键**
|
||
|
||
- `Ctrl + /`：切换源代码模式
|
||
|
||
- `Ctrl + B`：加粗
|
||
|
||
- `Ctrl + I`：斜体
|
||
|
||
- `Ctrl + K`：插入链接
|
||
|
||
- `Ctrl + Shift + I`：插入图片
|
||
|
||
- `Ctrl + T`：插入表格
|
||
|
||
- `Ctrl + Shift + M`：数学公式
|
||
|
||
- `Ctrl + 1~6`：标题级别
|
||
|
||
### 3. **与你的 DevOps 平台集成**
|
||
|
||
**配合 Gitea：**
|
||
|
||
1. 在 Typora 中编写 Markdown 文档
|
||
|
||
2. 保存到 Git 仓库目录
|
||
|
||
3. 使用 Git 命令或 Git 客户端提交到 Gitea
|
||
|
||
**配合 MkDocs：**
|
||
|
||
yaml
|
||
|
||
# mkdocs.yml 配置 Typora 兼容
|
||
|
||
markdown_extensions:
|
||
|
||
- admonition
|
||
- codehilite
|
||
- footnotes
|
||
- meta
|
||
- toc:
|
||
permalink: true
|
||
- pymdownx.superfences
|
||
- pymdownx.tabbed
|
||
|
||
### 4. **图片处理配置**
|
||
|
||
yaml
|
||
|
||
# Typora 偏好设置 → 图像
|
||
|
||
- 复制图片到 ./${filename}.assets 文件夹
|
||
- 对本地位置的图片应用上述规则
|
||
- 对网络位置的图片应用上述规则
|
||
|
||
## 主题和样式
|
||
|
||
### 内置主题：
|
||
|
||
1. **Github** - GitHub 风格
|
||
|
||
2. **Night** - 深色主题
|
||
|
||
3. **Pixyll** - 简洁风格
|
||
|
||
4. **Whitey** - 纯白简洁
|
||
|
||
### 自定义 CSS：
|
||
|
||
1. 打开主题文件夹：`文件 → 偏好设置 → 外观 → 打开主题文件夹`
|
||
|
||
2. 创建 `user.base.user.css` 文件
|
||
|
||
3. 添加自定义样式：
|
||
|
||
css
|
||
|
||
/* 自定义样式 */
|
||
body {
|
||
font-family: "Microsoft YaHei", sans-serif;
|
||
max-width: 900px;
|
||
margin: 0 auto;
|
||
}
|
||
|
||
img {
|
||
border-radius: 8px;
|
||
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
|
||
}
|
||
|
||
## 常见问题解决
|
||
|
||
### Q1: 下载速度慢？
|
||
|
||
- 使用国内镜像站
|
||
|
||
- 使用下载工具（IDM、迅雷等）
|
||
|
||
- 尝试 GitHub Releases
|
||
|
||
### Q2: 安装失败？
|
||
|
||
**Windows：**
|
||
|
||
- 以管理员身份运行
|
||
|
||
- 关闭杀毒软件临时
|
||
|
||
- 检查系统版本（需要 Win7 以上）
|
||
|
||
**macOS：**
|
||
|
||
bash
|
||
|
||
# 如果提示 "已损坏"
|
||
|
||
sudo xattr -rd com.apple.quarantine /Applications/Typora.app
|
||
|
||
**Linux：**
|
||
|
||
bash
|
||
|
||
# 依赖问题
|
||
|
||
sudo apt --fix-broken install
|
||
|
||
### Q3: 许可证问题？
|
||
|
||
- 检查网络连接
|
||
|
||
- 确认邮箱和密钥正确
|
||
|
||
- 访问 https://typora.io/dev_release.html 检查服务状态
|
||
|
||
## 推荐配置（用于 DevOps 文档）
|
||
|
||
### 1. **工作流设置**
|
||
|
||
text
|
||
|
||
1. 在 Typora 中编写 Markdown
|
||
2. 保存到 Git 管理的 docs/ 目录
|
||
3. 使用 MkDocs 构建静态网站
|
||
4. 部署到服务器或 GitHub Pages
|
||
|
||
### 2. **写作模板**
|
||
|
||
创建模板文件 `template.md`：
|
||
|
||
markdown
|
||
|
||
---
|
||
|
||
title: {{title}}
|
||
date: {{date}}
|
||
tags:
|
||
category:
|
||
|
||
---
|
||
|
||
# {{title}}
|
||
|
||
## 概述
|
||
|
||
## 详细内容
|
||
|
||
## 参考链接
|
||
|
||
### 3. **自动化脚本**
|
||
|
||
bash
|
||
|
||
#!/bin/bash
|
||
|
||
# auto_build.sh - 自动构建文档
|
||
|
||
cd /path/to/docs
|
||
typora --wait-for-signal-to-close document.md
|
||
mkdocs build
|
||
git add .
|
||
git commit -m "Update documentation"
|
||
git push
|
||
|
||
## 总结
|
||
|
||
Typora 是一款优秀的 Markdown 编辑器，特别适合：
|
||
|
||
- 个人知识库管理（配合你的 MkDocs）
|
||
|
||
- 技术文档编写
|
||
|
||
- 日常笔记记录
|
||
|
||
如果你需要完全免费的方案，建议考虑 **MarkText** 或 **Obsidian**。对于你的 DevOps 平台，Typora 的所见即所得特性确实能提升 Markdown 文档的编写体验。
|
||
|
||
本回答由 AI 生成，内容仅供参考，请仔细甄别。
|
||
|
||
image.png
|
||
|
||
PNG 33.06KB
|
||
|
||
下载好了，如何安装
|
||
|
||
根据你提供的信息，你已经下载了 MarkText 的 Windows 安装文件。以下是详细的安装步骤：
|
||
|
||
## 方法一：使用安装向导（推荐）
|
||
|
||
### 步骤：
|
||
|
||
1. **找到下载的文件**
|
||
|
||
- 通常在 `Downloads`（下载）文件夹中
|
||
|
||
- 文件名类似：`marktext-setup-x.x.x.exe`（x.x.x 是版本号）
|
||
|
||
2. **运行安装程序**
|
||
|
||
- 双击 `.exe` 文件
|
||
|
||
- 如果出现安全警告，点击"运行"或"更多信息 → 仍要运行"
|
||
|
||
3. **选择安装类型**
|
||
|
||
text
|
||
|
||
Install for: （选择安装范围）
|
||
□ Just me (当前用户)
|
||
☑ All users (requires admin privileges) (所有用户，需要管理员权限)
|
||
|
||
- **推荐选择**：`All users`（需要管理员权限）
|
||
|
||
4. **选择安装位置**
|
||
|
||
- 默认位置：`C:\Program Files\MarkText\`
|
||
|
||
- 可以点击"Browse"更改安装路径
|
||
|
||
5. **创建快捷方式**
|
||
|
||
- 桌面快捷方式（推荐勾选）
|
||
|
||
- 开始菜单文件夹
|
||
|
||
6. **完成安装**
|
||
|
||
- 点击"Install"开始安装
|
||
|
||
- 安装完成后点击"Finish"
|
||
|
||
## 方法二：使用包管理器安装
|
||
|
||
### 如果已经下载了安装包，直接使用方法一即可。以下是使用包管理器的方法：
|
||
|
||
### 1. **使用 Chocolatey**（需要先安装 Chocolatey）
|
||
|
||
cmd
|
||
|
||
# 以管理员身份打开命令提示符或 PowerShell
|
||
|
||
choco install marktext
|
||
|
||
### 2. **使用 Winget**（Windows 11 自带，Win10 可能需要安装）
|
||
|
||
cmd
|
||
|
||
# 以管理员身份打开终端
|
||
|
||
winget install marktext
|
||
|
||
## 验证安装
|
||
|
||
### 检查是否安装成功：
|
||
|
||
1. **启动程序**
|
||
|
||
- 从开始菜单搜索"MarkText"
|
||
|
||
- 双击桌面快捷方式（如果创建了）
|
||
|
||
2. **命令行验证**
|
||
|
||
cmd
|
||
|
||
# 打开命令提示符或 PowerShell
|
||
|
||
marktext --version
|
||
|
||
# 或
|
||
|
||
marktext --help
|
||
|
||
3. **文件关联**（可选）
|
||
|
||
- 安装后，MarkText 可能会询问是否关联 `.md` 文件
|
||
|
||
- 点击"是"即可用 MarkText 打开所有 Markdown 文件
|
||
|
||
## 首次使用设置
|
||
|
||
### 1. **选择主题**
|
||
|
||
打开 MarkText 后，你会看到：
|
||
|
||
- **Dark Theme** - 深色主题
|
||
|
||
- **Light Theme** - 浅色主题
|
||
|
||
- **Graphite Theme** - 石墨主题
|
||
|
||
- **Ulysses Theme** - Ulysses 风格
|
||
|
||
- **Material Dark** - Material 深色
|
||
|
||
- **Cadmium Light** - 镉浅色
|
||
|
||
### 2. **基本配置**
|
||
|
||
按 `Ctrl+,` 打开设置：
|
||
|
||
json
|
||
|
||
{
|
||
// 编辑器设置
|
||
"autoSave": true, // 自动保存
|
||
"autoSaveDelay": 1000, // 自动保存延迟（毫秒）
|
||
"defaultFontSize": 16, // 默认字体大小
|
||
|
||
// 编辑器行为
|
||
"editorLineWidth": 800, // 编辑器行宽
|
||
"fontFamily": "Arial", // 字体
|
||
|
||
// Markdown 设置
|
||
"preferLooseListItem": true, // 宽松列表
|
||
"bulletListMarker": "-", // 列表标记
|
||
|
||
// 图像设置
|
||
"imageFolderPath": "assets", // 图片保存文件夹
|
||
"setImageFolder": true // 自动创建图片文件夹
|
||
}
|
||
|
||
### 3. **设置中文界面**
|
||
|
||
1. 按 `Ctrl+,` 打开设置
|
||
|
||
2. 搜索 `locale`
|
||
|
||
3. 将 `locale` 改为 `zh-CN`
|
||
|
||
4. 重启 MarkText
|
||
|
||
## 常见问题解决
|
||
|
||
### Q1：安装时提示"需要管理员权限"？
|
||
|
||
- **解决方法**：
|
||
|
||
1. 右键点击安装程序
|
||
|
||
2. 选择"以管理员身份运行"
|
||
|
||
3. 或者选择"Just me"（仅当前用户）安装选项
|
||
|
||
### Q2：安装后无法启动？
|
||
|
||
- **解决方法**：
|
||
|
||
1. 重启电脑
|
||
|
||
2. 检查防病毒软件是否阻止
|
||
|
||
3. 重新安装
|
||
|
||
4. 查看 Windows 事件查看器中的错误信息
|
||
|
||
### Q3：如何卸载？
|
||
|
||
cmd
|
||
|
||
# 方法1：控制面板卸载
|
||
|
||
# 方法2：使用包管理器
|
||
|
||
winget uninstall marktext
|
||
|
||
# 或
|
||
|
||
choco uninstall marktext
|
||
|
||
## 快速开始使用
|
||
|
||
### 1. **创建第一篇文档**
|
||
|
||
1. 按 `Ctrl+N` 新建文件
|
||
|
||
2. 输入内容：
|
||
|
||
markdown
|
||
|
||
# 我的第一篇 Markdown
|
||
|
||
## 这是副标题
|
||
|
||
- 列表项1
|
||
- 列表项2
|
||
|
||
**粗体文本** *斜体文本*
|
||
|
||
[链接](https://example.com)
|
||
|
||
3. 按 `Ctrl+S` 保存
|
||
|
||
### 2. **常用快捷键**
|
||
|
||
- `Ctrl+N`：新建文件
|
||
|
||
- `Ctrl+O`：打开文件
|
||
|
||
- `Ctrl+S`：保存
|
||
|
||
- `Ctrl+Shift+S`：另存为
|
||
|
||
- `Ctrl+/`：切换源代码模式
|
||
|
||
- `Ctrl+B`：加粗
|
||
|
||
- `Ctrl+I`：斜体
|
||
|
||
- `Ctrl+K`：插入链接
|
||
|
||
- `Ctrl+Shift+I`：插入图片
|
||
|
||
### 3. **与你的 DevOps 平台集成**
|
||
|
||
将 MarkText 作为你的 Markdown 编辑器：
|
||
|
||
bash
|
||
|
||
# 在 Git 仓库中编辑文档
|
||
|
||
cd /path/to/your/docs
|
||
|
||
# 用 MarkText 打开文件
|
||
|
||
marktext README.md
|
||
|
||
# 或
|
||
|
||
marktext .
|
||
|
||
## 高级功能
|
||
|
||
### 1. **多标签页**
|
||
|
||
- 支持同时打开多个文件
|
||
|
||
- 标签页可拖拽重新排列
|
||
|
||
### 2. **多种编辑模式**
|
||
|
||
- **源代码模式** - 纯文本编辑
|
||
|
||
- **打字机模式** - 当前行居中
|
||
|
||
- **专注模式** - 淡化其他内容
|
||
|
||
### 3. **导出功能**
|
||
|
||
支持导出为：
|
||
|
||
- HTML
|
||
|
||
- PDF
|
||
|
||
- 纯文本
|
||
|
||
### 4. **Git 集成**
|
||
|
||
内置简单的 Git 支持：
|
||
|
||
- 显示 Git 状态
|
||
|
||
- 提交消息
|
||
|
||
- 差异对比
|
||
|
||
## 配置为默认 Markdown 编辑器
|
||
|
||
### Windows 10/11：
|
||
|
||
1. 右键点击 `.md` 文件
|
||
|
||
2. 选择"打开方式" → "选择其他应用"
|
||
|
||
3. 找到 MarkText，勾选"始终使用此应用打开 .md 文件"
|
||
|
||
4. 点击"确定"
|
||
|
||
完成安装后，你就可以用 MarkText 来编写你的 MkDocs 文档、技术笔记等，配合你的 DevOps 平台使用了！
|
||
|
||
image.png
|
||
|
||
PNG 64.83KB
|
||
|
||
点击哪个文件安装呢？
|
||
|
||
从你提供的文件列表来看，这是一个 **MarkText 的源代码项目目录**，而不是可以直接安装的安装程序。
|
||
|
||
让我帮你分析一下：
|
||
|
||
## 📁 **目录结构分析**
|
||
|
||
text
|
||
|
||
├── docs/ # 文档文件夹
|
||
├── src/ # 源代码文件夹
|
||
├── static/ # 静态资源
|
||
├── resources/ # 应用资源
|
||
├── package.json # Node.js 项目配置文件
|
||
├── electron-builder.yml # Electron 构建配置
|
||
└── 其他配置文件...
|
||
|
||
## 🚨 **重要：这不是安装包！**
|
||
|
||
你下载的是 **MarkText 的源代码**，需要**编译构建**后才能得到安装程序。
|
||
|
||
## 🛠️ **如何正确安装 MarkText**
|
||
|
||
你有两个选择：
|
||
|
||
### **选择一：下载正式安装包（推荐）**
|
||
|
||
1. **访问 MarkText 官方发布页**：
|
||
[Releases · marktext/marktext · GitHub](https://github.com/marktext/marktext/releases)
|
||
|
||
2. **下载正确的安装包**：
|
||
|
||
- Windows：`marktext-setup-x.x.x.exe` （x.x.x是版本号）
|
||
|
||
- macOS：`marktext-x.x.x.dmg`
|
||
|
||
- Linux：`marktext-x.x.x-x86_64.AppImage`
|
||
|
||
3. **双击安装包安装**
|
||
|
||
### **选择二：从源码构建安装**
|
||
|
||
如果你确实想从这个源码构建：
|
||
|
||
bash
|
||
|
||
# 1. 安装 Node.js (v14+)
|
||
|
||
# 从 https://nodejs.org/ 下载安装
|
||
|
||
# 2. 安装 Yarn
|
||
|
||
npm install -g yarn
|
||
|
||
# 3. 进入项目目录
|
||
|
||
cd "你下载的文件夹路径"
|
||
|
||
# 4. 安装依赖
|
||
|
||
yarn install
|
||
|
||
# 5. 运行开发版本
|
||
|
||
yarn run dev
|
||
|
||
# 6. 构建安装包（可选）
|
||
|
||
yarn run build
|
||
|
||
## 📦 **快速对比**
|
||
|
||
| 类型 | 文件 | 说明 |
|
||
| --------- | --------------------------- | ------ |
|
||
| **✅ 安装包** | `.exe`, `.dmg`, `.AppImage` | 双击即可安装 |
|
||
| **❌ 源代码** | 文件夹 + 配置文件 | 需要编译构建 |
|
||
|
||
## 🔍 **检查你下载的文件**
|
||
|
||
如果你是通过以下方式下载的：
|
||
|
||
- **GitHub 的绿色 "Code" 按钮** → 下载的是源代码
|
||
|
||
- **Git clone 命令** → 下载的是源代码
|
||
|
||
- **Release 页面的 "Source code"** → 下载的是源代码
|
||
|
||
**正确的方式**：在 Release 页面找到 **Assets**（资源）部分，下载那里的文件。
|
||
|
||
## 🎯 **立即获取安装包的步骤**
|
||
|
||
1. **访问**：[Releases · marktext/marktext · GitHub](https://github.com/marktext/marktext/releases)
|
||
|
||
2. **找到最新版本**（如 v0.17.1）
|
||
|
||
3. **展开 "Assets"** 部分
|
||
|
||
4. **下载对应系统的文件**：
|
||
|
||
text
|
||
|
||
Windows用户下载：
|
||
marktext-setup-x.x.x.exe （约 90 MB）
|
||
或
|
||
marktext-setup-x.x-x64.exe
|
||
|
||
## 💡 **如果你已经下载了源代码**
|
||
|
||
你可以：
|
||
|
||
1. **保留源代码**：用于学习或二次开发
|
||
|
||
2. **删除源代码**：如果你只需要使用软件
|
||
|
||
## 📝 **总结建议**
|
||
|
||
**普通用户**：直接去 Release 页面下载安装包，简单快捷
|
||
**开发者**：可以保留源代码进行学习和定制
|
||
|
||
**记住这个关键点**：
|
||
|
||
- **`.exe` 文件** = 可以直接安装
|
||
|
||
- **文件夹+配置文件** = 需要编译构建
|
||
|
||
现在就去 Release 页面下载真正的安装包吧！这样你就能立即开始使用 MarkText 了。
|