antvis / antvis.github.io

@afc163 基础设施搭建 + 所有网站迁移，会给各个仓库提 PR
框架各自的负责人：内容填充 + 文档迁移 + 国际化 + 提需求

✨ 子站点改造开始了！

目前 gatsby-theme-antv 的基础功能已经就绪，细节功能还在补充，下周开始做视觉还原，各个子站点今天开始已经进行接入了：

站点	仓库地址	负责人	状态	预览站点
AntV 首页	https://github.com/antvis/antvis.github.io	@Yanyan-Wang	🚀	https://antvis.github.io
G2	https://github.com/antvis/g2	@simaQ	🚀	https://antvis.github.io/g2
G2Plot	https://github.com/antvis/g2plot	@paleface001	🚀	https://antvis.github.io/g2plot
ChartCube	内网	璆鸣	🚀	-
F2	https://github.com/antvis/f2	索丘	🚀	https://antvis.github.io/f2
G6	https://github.com/antvis/g6	@baizn	🚀	https://antvis.github.io/g6
L7	https://github.com/antvis/l7	@lzxue	🚀	https://antvis.github.io/l7
Graphin	https://github.com/antvis/graphin	山果	🚀	https://antvis.github.io/graphin
G	https://github.com/antvis/g	@dengfuping	🚀	https://antvis.github.io/g

未开始：⚠️
进行中：♻️
待验收：🚀
完成验收：✨

接入方式

这里写一个简单的接入步骤，完整请参考 https://github.com/antvis/gatsby-theme-antv 的 README 和下列示例网站进行接入：

安装依赖

npm install gatsby @antv/gatsby-theme-antv react-i18next gh-pages --save-dev

确保 @antv/gatsby-theme-antv 版本在 0.9.7 或以上。

添加 `gatsby-config.js` 和 `gatsby-browser.js` 文件

两个文件的内容参考：

GATrackingId 的配置请联系偏右，我去 GA 后台生成一个。

（可选）添加 babel-preset-gatsby

如果你的项目有 .babelrc 文件，需要加入相关的 preset

npm install babel-preset-gatsby --save-dev

修改 .babelrc，确保放在 presets 的最后。

{
  "presets": [
      ...
+   "babel-preset-gatsby"
  ]
}

可以参考：https://github.com/antvis/g2/pull/1605/files

忽略临时发布目录

public 和 .cache 是 gatsby 生成的静态文件目录和临时目录，不需要提交，将它们加到 .gitignore 目录里。

添加相关的 scripts 命令

https://github.com/antvis/g2plot/blob/97fb088e03ab9561d2377386877b071ba509cec1/package.json#L22-L26

  "scripts": {
    ...
+   "start": "npm run site:develop",
+   "site:develop": "gatsby develop --open -H 0.0.0.0",
+   "site:build": "npm run site:clean && gatsby build --prefix-paths",
+   "site:clean": "gatsby clean",
+   "site:deploy": "npm run site:build && gh-pages -d public",
    ...
  }

然后运行 npm start 尝试一下，访问 https://127.0.0.1:8000 即可看到页面效果。

创建首页

创建 site/pages 目录
创建 site/pages/index.zh.ts 和 site/pages/index.en.ts 分别对应中英文首页。
创建 site/locale.json 统一存放国际化配置。

如果项目不支持 ts，index.zh.js 也可以。

内容参考 https://github.com/antvis/g2plot/blob/master/site/

将文档迁移到 docs 目录下

docs 文件内容参考 https://github.com/antvis/g2plot/tree/master/docs/manual
头部文档和侧边文档的入口配置在 gatsby-config.js 内。

所有 md 文件需要用下列格式定义相关属性。

---
title: 快速上手
order: 1
---

内容

可以用 redirect_from 字段来定义顶部导航的默认文档。比如下面所有 zh/docs/manual 的链接（通常放在顶部导航）会跳转到下面这个文档上。

---
title: 简介
order: 0
redirect_from:
  - /zh/docs/manual
---

注意，需要同时提供中英文两个版本的文档文件，暂时没翻译就复制一份中文文档即可。

将演示迁移到 examples 目录下

参考 https://github.com/antvis/g2plot/blob/master/examples/

头部导航的演示入口在 gatsby-config.js
项目用到的 json 数据文件放在 examples/data 下，使用时遇到 404 需要注意相对路径问题：https://github.com/antvis/g2plot/pull/177。当然也可以传到 basement cdn 上用绝对地址来调用。
在 gatsby-browser.js 里添加演示代码里用到的 import 全局变量，只有添加过的才可以 import g2plot from '@antv/g2plot';
演示的分类和图标设置在 https://github.com/antvis/g2plot/blob/68633854bfcdd7d61cf4dd8415a678de1af20b0e/gatsby-config.js#L54-L71
如果顶部菜单不需要 examples，从 navs 去掉 slug 为 examples 得这一项即可，examples 字段也可以删掉。

自定义顶部菜单

在 gatsby-config.js 的 navs 字段里可以定义修改菜单。
target: '_blank' 可以新窗口打开。

自定义页面

在 site/pages 里创建文件即可，custom.zh.js 对应 /zh/custom custom.en.js 对应 /en/custom。
所有页面会自动加上通用头尾，如果不需要，给页面 Component 加上 noLayout = true：

import React from 'react';
import { useTranslation } from 'react-i18next';

const Indepent = () => {
  const { t } = useTranslation();
  return <>{t('独立页面')}</>;
};

Indepent.noLayout = true;

export default Indepent;

国际化文案配置

使用 react-i18next 作为内建的国际化方案，使用时只需要 const { t, i18n } = useTranslation(); 即可。API 参考 react-i18next 官方文档使用。国际化文案的键值对统一放在项目下的 site/locale.json 内，以中文作为 key，英文作为翻译内容。

国际化文案统一存放的 json：https://github.com/antvis/antvis.github.io/blob/master/site/locale.json
使用用法：

antvis.github.io/site/pages/index.zh.tsx

Line 13 in 3296c99

{t('首页')}
相关文档：https://react.i18next.com/latest/usetranslation-hook

使用图片

可以用 basement cdn
可以放在本地 src/images 目录下：

antvis.github.io/site/pages/index.zh.tsx

Line 5 in 3296c99

import astronaut from '../images/gatsby-astronaut.png';

开启 gh-pages 服务

npm run site:deploy 之后会部署到 gh-pages 分支上，访问路径为：https://antvis.github.io/xxx

（可选）开启 netlify 预览服务

https://app.netlify.com/
设置构建命令为 npm run site:build
设置部署目录为 public
~~设置环境变量 GATSBY_PATH_PREFIX 为 / 以保证根域名的预览。~~ 不需要了
开启 Pull Request 的评论 hooks，这样发 PR 时机器人会自动回复预览地址。

开启之后 PR 会有预览的地址：antvis/G#234 (comment)

注意 ⚠️⚠️⚠️

~~首页可以等等，我们会提一些通用的 Banner、Features 组件方便大家统一开发。~~ 十吾开发好了组件了，可以开始了！https://github.com/antvis/gatsby-theme-antv#components
所有文档和演示请自行补充完整，并保证中英文两个版本都能正确渲染。
头尾不用管，会统一更新。
设计稿，首页的视觉还原，网站具体内容请自行和设计师对接。
开始接入后，请到这里更新一下表格的进度。
navs examples docs 的具体配置参考：https://github.com/antvis/gatsby-theme-antv#usage
一些主题用法可以参考这些第三方库文档。
有任何接入问题或者需求请联系 @afc163 ！！！

时间点

11-09 之前所有的 antvis.github.io/xxx 页面要能访问，文档和演示能用。

@afc163 偏右老师，Graphin站点已经接入：https://antvis.github.io/graphin/
文档明天开始准备，陆续更新。

Graphin首页和antv官方保持一致，不需要写

要写的，主题不包括首页内容。
注意切换为英文的所有页面。
graphin studio 页面可以去掉头尾，具体见 https://github.com/antvis/gatsby-theme-antv/blob/master/example/site/pages/independent.zh.tsx

@afc163 好的~

旧版本网站地址收集，新网站上线后做一个跳转。

请问一下，为啥迁移站点，感觉之前挺好的了，gatsby主题会带来额外增益么？

补充一些后面添加的功能：

网站搜索：antvis/gatsby-theme-antv#79
Html 源码展示：antvis/gatsby-theme-antv#83
所有图表页面：antvis/gatsby-theme-antv#88
多版本选择切换：antvis/gatsby-theme-antv#85

AntV 官网改造