google/webfundamentals

Web Fundamentals 技术文档

镜像概述和主要用途

Web Fundamentals是一个多设备Web开发的技术文档中心，目标是为现代Web开发者构建一个像developer.android.com或iOS Dev Center那样精选且全面的资源平台。该项目基于Jekyll构建，通过Gulp进行任务管理，支持多语言内容和本地预览，便于开发者查阅和贡献Web开发技术文档。

核心功能和特性

• 多设备Web开发资源：提供全面的多设备Web开发技术文档
• Jekyll构建：基于Jekyll静态站点生成器，支持内容模块化和模板化
• Gulp任务管理：通过Gulp自动化处理样式编译、JavaScript构建和站点部署
• 多语言支持：支持多语言内容，可通过语言参数指定构建特定语言版本
• 增量构建：支持按语言或站点部分进行增量构建，提升构建速度
• 本地预览：提供本地开发服务器，支持实时更新预览

使用场景和适用范围

• Web开发者查阅多设备Web开发技术文档
• 开发人员本地构建和预览文档站点
• 贡献者提交文档更新和翻译
• 团队协作维护Web开发技术文档库

详细使用方法和配置说明

安装依赖

构建和运行项目需安装Ruby、Node和NPM。以下是Mac系统的安装步骤：

1. 安装https://developer.apple.com/xcode/downloads/
2. 安装Node.js：https://nodejs.org/en/
3. 安装RVM：

   bash
   curl -sSL https://get.rvm.io | bash
   

4. 设置RVM默认Ruby版本为2.2.0：

   bash
   rvm install ruby-2.2.0
   rvm --default use 2.2.0
   

5. 安装Pygments：

   bash
   easy_install pygments
   

6. 安装Bundler：

   bash
   gem install bundler
   

7. 安装RubyGems依赖（Jekyll和Kramdown）：

   bash
   rvm . do bundle install
   

8. 安装Gulp CLI：

   bash
   npm install -g gulp
   

9. 安装npm依赖：

   bash
   npm install
   

10. 获取App Engine SDK并解压到项目根目录下的google_appengine文件夹，添加到环境变量：

    bash
    PATH=./google_appengine:$PATH
    

运行站点

使用以下命令启动站点：

bash
gulp

该命令会编译样式和JavaScript，通过Jekyll构建站点，并启动端口为7331的本地服务器，可通过http://localhost:7331/web/%E8%AE%BF%E9%97%AE%E3%80%82%E6%96%87%E4%BB%B6%E4%BF%AE%E6%94%B9%E5%90%8E%E4%BC%9A%E8%87%AA%E5%8A%A8%E8%A7%A6%E5%8F%91%E7%9B%B8%E5%BA%94%E7%9A%84Gulp%E4%BB%BB%E5%8A%A1%E9%87%8D%E6%96%B0%E6%9E%84%E5%BB%BA%E3%80%82

加快Jekyll构建速度

可通过指定语言和/或站点部分来加快构建速度：

• 构建单一语言：

  bash
  gulp --lang en
  

• 构建特定部分：

  bash
  gulp --section shows
  

• 组合使用：

  bash
  gulp --lang en --section shows
  

学习Jekyll和Liquid

可通过访问http://localhost:7331/web/styleguide/%E6%9F%A5%E7%9C%8B%E6%A0%B7%E5%BC%8F%E6%8C%87%E5%8D%97%EF%BC%8C%E4%BA%86%E8%A7%A3Jekyll%E5%92%8CLiquid%E7%9A%84%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95%E3%80%82

项目结构

项目基于Jekyll构建，结构如下：

/appengine-config - 静态内容托管服务器配置
/gulp-tasks - Gulp任务按功能拆分（样式、脚本等）
/src - 文档源文件
  /content - 多语言内容
    /en - 基础语言文件夹，子文件夹为站点各部分
      /fundamentals
      /showcase
      /shows
      ...等...
    /<langcode> - 特定语言覆盖内容，遵循en的结构
  /jekyll - Jekyll相关配置
    /_config - 页面设置定义文件
    /_data - 静态字符串及其翻译
    /_includes - HTML片段，可在页面中引用
    /_layouts - 页面布局模板，在文档YAML中引用
    /_plugins - Web Fundamentals核心插件
  /static - 静态资源
    /imgs - 图片资源
    /scripts - JavaScript文件（仅本地使用，不用于最终部署）
    /styles - Sass样式文件
    /third_party - 第三方资源
  /tests - 测试文件
  /tools - 工具脚本

站点生成文件位于/build目录，该目录不纳入版本控制。

其他说明

翻译

翻译相关内容请参考翻译指南。

构建Shows

需要安装Python https://developers.google.com/api-client-library/python/start/installation%EF%BC%9A

bash
pip install --upgrade google-api-python-client

内容计划

Web Fundamentals的内容计划通过GitHub Issues和站点结构与内容清单文档进行跟踪。

发布状态

项目于2014年4月底软启动，6月正式发布v1版本，目前采用六周滚动发布周期。

贡献

Web Fundamentals是开源项目，欢迎贡献。提交拉取请求前，请先查看贡献指南并确保已创建描述修复或新内容的issue，否则可能无法接受拉取请求。