Marlin 文档项目

关于

本仓库包含 Marlin 3D 打印机固件的原始文档，这些文档会自动部署到 marlinfw.org。该文档是开放的，并在 GitHub 上可用，任何人都可以通过完善、更正或创建文章来做出贡献。

技术细节

Marlin Documentation 项目使用以下技术构建：

如何贡献

要处理文档，首先将此仓库 fork 到你的 GitHub 账户，然后在本地克隆 你的 MarlinDocumentation fork。在作为 Pull Request 提交到 master 分支之前，你应该在自己的 fork 中完成所有工作。你可以下载 GitHub Desktop 应用并使用 GitHub 的“在 Desktop 中打开”选项，或者从你自己的桌面打开终端/cmd 窗口并执行：

例如，切换到 C:\ 的根目录：

cd C:\

克隆 Marlin 文档仓库：

git clone https://github.com/MarlinFirmware/MarlinDocumentation.git

这将在本地创建一个链接到你 fork 的 C:\MarlinDocumentation 文件夹。

若要添加新文档或编辑现有文档，请首先创建一个新分支]，作为 master 分支的副本。你可以通过 GitHub 网页界面、GitHub Desktop 或命令行来完成此操作。

如果你的新文档是关于“土豆泥”的，请相应地命名新分支：

git checkout master -b doc-mashed_potatoes

在 _docs 文件夹中，添加新文件 mashed-potatoes.md 并尽情发挥你的创造力。当你觉得你的杰作准备好与世界分享时，提交更改并将其推送到 你的 Marlin Documentation fork。这最容易通过 GitHub Desktop 应用完成，但以下是供参考的命令行命令：

git add mashed-potatoes.md
git commit -m "Added a new document about potatoes"
git push

接下来，向上游仓库发起一个新的 Pull Request（MarlinFirmware/MarlinDocumentation）。

[!TIP] 如果你是 git 贡献的新手，请查阅 GitHub 关于创建新分支、管理分支以及创建 Pull Requests的文档。

编码风格

这个基于 Jekyll 的网站基于 Markdown 语言，并使用了美味的 YAML 包装。请小心这种格式，因为即使是小的拼写错误也可能导致 Jekyll 拒绝该页面。如果你已按照下文描述安装了 Jekyll，你可以使用它来构建和预览文档，这将告诉你错误在哪里。

编辑风格

尽量保持中立、简洁和直接。除非避免使用个人代词会显得生硬，否则避免使用个人代词。在需要时提供图片并给出示例。检查你的拼写、语法和标点符号。

进行中

你可以使用 _tmp 文件夹用于进行中的工作，它们将不会包含在站点部署中。

本地 Jekyll 预览

如果你希望在提交之前能够预览你的贡献，你需要在系统上安装 Jekyll。以下是 Windows 和 macOS 的说明：

在 Windows 上安装 Ruby

从 RubyInstaller Download Archives 下载并安装 Ruby+Devkit 3.3.4。安装时使用默认选项。
在安装向导的最后一个阶段运行 ridk install 步骤。为 MSYS2 and MINGW development tool chain 选择选项 3。这对于安装带有原生扩展的 gems 是必需的。您可以在 RubyInstaller 文档中找到有关此内容的更多信息。

[!TIP] 一旦 MSYS2 and MINGW development toolchain 安装完成，安装向导将重新提示应安装哪些组件。如果您看到上方有“Install MSYS2 and MINGW development toolchain succeeded”消息，您可以关闭命令提示符窗口并继续以下操作。

打开一个新的命令提示符，以使 PATH 环境变量的更改生效，然后检查一切是否正常工作：
```
ruby -v
```
如果报告 ruby 3.3.4 (2024-07-09 revision be1089c8ec)，则继续设置 Marlin 文档项目。

在 macOS 上安装 Ruby

[!NOTE] Ruby 可能已预装，但 macOS 的“系统 Ruby”已过时、不再维护，且不推荐用于一般用途。

macOS 有许多流行的包管理器，但我们将介绍使用 Homebrew 和 MacPorts 进行安装。

安装一个包管理器。您不需要同时安装两者：
- 通过启动终端并运行以下命令来安装 Homebrew：
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

通过从 Installing MacPorts 页面下载并安装适用于您 macOS 版本的正确软件包来安装 MacPorts。
- 使用 MacPorts 安装软件包需要 Xcode 或 Xcode 命令行工具。您无需同时安装两者。这些工具可在 Apple 开发者计划网站上免费获取。无需 Apple 开发者计划会员资格，但您需要使用 Apple ID 登录。

安装 chruby 和 ruby-install：
- Homebrew：
```
brew install chruby ruby-install
```

MacPorts:
```
sudo port install chruby ruby-install
```

安装 Ruby 3.3.4：
```
ruby-install ruby 3.3.4
```

配置、构建和安装过程需要几分钟。

配置您的 shell 以自动使用 chruby：

Homebrew：

echo "" >> ~/.zshrc
echo "# Ruby Configuration" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.3.4" >> ~/.zshrc

MacPorts:

echo "" >> ~/.zshrc
echo "# Ruby Configuration" >> ~/.zshrc
echo "source ${prefix}/opt/local/share/chruby/chruby.sh" >> ~/.zshrc
echo "source ${prefix}/opt/local/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.3.4" >> ~/.zshrc

退出并重新启动 Terminal，然后检查一切是否正常工作：
```
ruby -v
```
它应该报告 ruby 3.3.4 (2024-07-09 revision be1089c8ec)。如果没有，请重复上述步骤。

[!NOTE] 使用 ruby-install 时，您将在 ~/.rubies/ 中找到您的 Ruby 安装，并可以使用 chruby 在它们之间切换。由于对 ~/.zshrc 所做的更改，Terminal 中的新 zsh 实例将默认使用 3.3.4。

继续设置 Marlin Documentation 项目。（注意 bundler 已包含在内。）

在 Ubuntu 上安装 Ruby

确保 APT 是最新的：
```
sudo apt update
```

安装先决条件：

sudo apt install git curl libssl-dev libreadline-dev zlib1g-dev autoconf bison build-essential libyaml-dev libreadline-dev libncurses5-dev libffi-dev libgdbm-dev

安装 rbenv：

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

安装 Ruby 3.3.4：
```
rbenv install 3.3.4
rbenv global 3.3.4
```

[!NOTE] 使用 rbenv 时，你可以在 ~/.rbenv/versions/ 中找到你的 Ruby 安装，并可以使用 rbenv global <version> 在它们之间切换。

检查 Ruby 版本：
```
ruby -v
```
它应该报告 ruby 3.3.4 (2024-07-09 revision be1089c8ec)。如果没有，请重复上述步骤。

在你的 ~/.bashrc 文件中添加环境变量以配置 gem 安装路径：

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

安装 Bundler 宝石：
```
gem install bundler
```
前往 Set up Marlin Documentation project。

Set up Marlin Documentation project

安装 Ruby 后，使用 Bundler 设置 Marlin Documentation 项目。打开命令提示符或终端，并 cd 到 你的 Marlin Documentation fork 的工作路径。执行以下命令：

rm -f Gemfile.lock
bundle config set path 'vendor/bundle'
bundle install

[!NOTE] 您只需执行一次上述命令即可完成安装。如果在此阶段出现错误，您可能需要更新 Ruby 安装、修复 Ruby 环境或解决 Ruby gems 之间的依赖关系。

Jekyll 基础

Jekyll 使用 YAML、Markdown、Liquid 和 HTML 的组合来定义站点内容和布局。一个 _config.yml 文件定义了与子文件夹对应的“集合”的站点结构。网站会被“编译”以生成静态 HTML 和 Javascript。站点中最重要的文件夹是：

_layouts 包含通用布局（也称为页面模板）。
_includes 包含被其他布局引用的部分布局。
_meta 用于存放顶级页面描述。
章节：_basics、_configuration、_development、_features、_gcode、_hardware……

预览内容

要启动一个迷你 Web 服务器并预览您的更改，请运行以下命令：

bundle exec jekyll serve --watch --incremental

使用 serve --watch --incremental 参数，Jekyll 会监视本地文件的变化，并在每次保存时触发站点的自动增量构建。它还会启动一个迷你 Web 服务器，以便在浏览器中通过 http://localhost:4000/ 预览文档。

[!TIP] 主要的 Marlin 仓库附带了 mfdoc 脚本，其中包含上述命令，作为预览文档的快捷方式。

License

本文档采用 GPLv3 许可证授权。