Expensify/App 文档站点开发指南：从搭建到部署全解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00503/article/details/148548464

Expensify/App 文档站点开发指南：从搭建到部署全解析

App Welcome to New Expensify: a complete re-imagination of financial collaboration, centered around chat. Help us build the next generation of Expensify by sharing feedback and contributing to the code. 项目地址: https://gitcode.com/gh_mirrors/app1/App

前言

Expensify/App 的文档站点是一个基于 Jekyll 构建的静态网站，为 Expensify 用户提供全面的产品使用指南。本文将深入解析该文档站点的技术架构、本地开发流程和内容管理方法，帮助开发者快速上手文档站点的维护工作。

环境搭建与本地测试

前置准备

在开始本地开发前，需要确保系统满足以下条件：

已安装 Ruby 2.6 或更高版本
已安装 Bundler 包管理器
已获取项目代码

安装步骤

安装 Bundler：
```
gem install bundler
```
进入 docs 目录并安装依赖：
```
cd docs
bundle install
```

常见问题解决

在 macOS 新版本上可能会遇到 Ruby 头文件路径问题，可通过以下命令解决：

cd /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX13.0.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0/
ln -sf universal-darwin22 universal-darwin21

启动本地服务器

生成文档路由：
```
npm run createDocsRoutes
```
启动 Jekyll 服务：
```
bundle exec jekyll serve --livereload
```
若遇到 EventMachine 扩展加载错误，可尝试：
```
gem uninstall eventmachine && bundle install
```

项目结构解析

文档站点采用标准的 Jekyll 项目结构，主要目录说明如下：

核心目录

_layouts：存放页面布局模板
- default.html：基础布局模板，包含公共 HTML 元素和资源引用
_includes：可复用组件
- 支持参数传递和嵌套，功能强大
assets：静态资源
- css：样式文件（支持 SASS 预处理）
- images：图片资源
- js：JavaScript 脚本
hubs：主题中心
- 按主题组织相关文章
- 支持子主题分组
articles：文章内容
- 按平台和主题分类存放
_data：全局数据
- routes.yml：定义站点结构和页面元数据

关键概念

平台(Platform)：Expensify Classic 和 New Expensify
中心(Hub)：相关文章的集合
文章(Article)：具体功能文档
子分类(Subcategory)：更细分的文章集合

内容管理指南

创建新主题中心

以在 New Expensify 平台下创建"Billing and Subscriptions"中心为例：

在 _data/_routes.yml 中添加中心定义：

- href: billing-and-subscriptions
  title: Billing & Subscriptions
  icon: /assets/images/subscription.svg
  description: 账单管理指南...

创建中心目录：

mkdir -p docs/new-expensify/hubs/billing-and-subscriptions

添加中心首页：

---
layout: default
title: Billing & Subscriptions
---

{% include hub.html %}

创建文章目录：

mkdir -p docs/articles/new-expensify/billing-and-subscriptions

添加新文章

复制模板文件到对应目录：

cp TEMPLATE.md docs/articles/expensify-classic/bank-accounts/Connect-ANZ.md

编辑文章内容：
- 使用 Markdown 语法
- 正确使用标题层级（# 一级标题，## 二级标题等）

添加图片：

![ANZ银行连接截图]({{site.url}}/assets/images/anz-connection.png){:width="100%"}

添加视频：

{% include video.html src="https://example-stream-provider.com/b81eabafe1391ab06901ddc19dcda161" %}

SEO 优化

在文章头部添加元信息：

---
title: ANZ银行账户连接指南
description: 详细说明如何将ANZ银行账户连接到Expensify
image: /assets/images/anz-preview.jpg
---

站点部署流程

文档站点采用自动化部署流程：

代码合并到主分支后触发部署流程
自动生成路由配置文件
构建 Jekyll 站点
部署到静态网站托管服务
最终发布到生产环境

最佳实践

命名规范：
- 文件名使用短横线代替空格（如 Freemium-Features.md）
- 保持命名一致性
内容组织：
- 合理使用子分类组织大量文章
- 保持层级清晰
版本控制：
- 重命名或删除内容时添加重定向
- 使用 redirects.csv 管理链接跳转
临时隐藏：
- 将文章移动到 Hidden 目录
- 添加重定向记录

通过本文的详细指南，开发者可以全面掌握 Expensify/App 文档站点的开发与维护工作，确保文档内容始终保持最新且易于用户访问。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考