搜索

[25478] 2016-09-12_使用GithubPages发布你的项目文档

文档创建者：s7ckTeam
浏览次数：2
最后更新：2025-01-19
2016-09-12_使用GithubPages发布你的项目文档 使 用   G i t h u b   P a g e s   发 布 你 的 项 目 文 档 原 创   译 者 ： B e s t o n y   L i n u x 中 国   2 0 1 6 - 0 9 - 1 2 你 可 能 比 较 熟 悉 如 何 用   G i t h u b   P a g e s   来 分 享 你 的 工 作 [ 1 ] ， 又 或 许 你 看 过 一 堂 [ 2 ] 教 你 建 立 你 的 第 一 个   G i t h u b   P a g e s   网 站 的 教 程 。 近 期   G i t h u b P a g e s   的 改 进 使 得 从 不 同 的 数 据 源 来 发 布 您 的 网 站 [ 3 ] 更 加 的 方 便 ， 其 中 的 来 源 之 一 就 是 你 的 仓 库 的   / d o c s   目 录 。 文 档 的 质 量 是 一 个 软 件 项 目 健 康 发 展 的 标 志 。 对 于 开 源 项 目 来 说 ， 维 护 一 个 可 靠 而 不 出 错 的 知 识 库 、 详 细 说 明 所 有 的 细 节 是 至 关 重 要 的 。 精 心 策 划 的 文 档 可 以 让 增 加 项 目 的 亲 切 感 ， 提 供 一 步 步 的 指 导 并 促 进 各 种 方 式 的 合 作 可 以 推 动 开 源 软 件 开 发 的 协 作 进 程 。 在   W e b   上 托 管 你 的 文 档 是 一 个 消 耗 时 间 的 挑 战 ， 而 且 对 于 它 的 发 布 和 维 护 也 没 有 省 事 的 办 法 ， 然 而 这 是 并 非 不 可 避 免 的 。 面 对 多 种 不 同 的 发 布 工 具 ， 又 是   F T P   服 务 器 ， 又 是 数 据 库 ， 文 件 以 各 种 不 同 的 方 式 存 放 在 不 同 的 位 置 下 ， 而 这 些 都 需 要 你 手 动 来 调 整 。 需 要 说 明 的 是 ， 传 统 的   W e b   发 布 方 式 提 供 了 无 与 伦 比 的 灵 活 性 和 性 能 ， 但 是 在 许 多 情 况 下 ， 这 是 以 牺 牲 简 单 易 用 为 代 价 的 。 当 作 为 文 档 使 用 时 ， 麻 烦 更 少 的 方 式 显 然 更 容 易 去 维 护 。 G i t H u b   P a g e s [ 4 ]   可 以 以 指 定 的 方 式 为 你 的 项 目 创 建 网 站 ， 这 使 得 它 天 然 地 适 合 发 布 和 维 护 文 档 。 因 为   G i t h u b   P a g e s   支 持   J e k y l l ， 所 以 你 可 以 使 用 纯 文 本 或   M a r k d o w n   来 书 写 你 的 文 档 ， 从 而 降 低 你 维 护 的 成 本 、 减 少 维 护 时 的 障 碍 。 J e k y l l   还 支 持 许 多 有 用 的 工 具 比 如 变 量 、 模 板 、 以 及 自 动 代 码 高 亮 等 等 ， 它 会 给 你 更 多 的 灵 活 性 而 不 会 增 加 复 杂 性 ， 这 些 你 在 一 些 笨 重 的 平 台 是 见 不 到 的 。 最 重 要 的 是 ， 在   G i t h u b   上 使 用   G i t H u b   P a g e s   意 味 着 你 的 文 档 和 代 码 可 以 使 用 诸 如   I s s u e s   和   P u l l   R e q u e s t s   来 确 保 它 得 到 应 有 的 高 水 平 维 护 ， 而 且 因 为   G i t H u b   P a g e s   允 许 您 发 布 代 码 库 主 分 支 上 的   / d o c s   目 录 ， 这 样 您 就 可 以 在 同 一 分 支 同 时 维 护 你 的 代 码 库 及 其 文 档 。 现 在 开 始 ！ 现 在 开 始 ！ 发 布 你 的 第 一 个 文 档 页 面 只 需 要 短 短 几 分 钟 。 1 .   在 你 的 仓 库 的 主 分 支 里 创 建 一 个   / d o c s / i n d e x . m d   文 件 。 2 .   把 你 的 内 容 以   J e k y l l   格 式 添 加 进 去 ， 并 提 交 你 的 修 改 。
3 .   查 看 你 的 仓 库 的 设 置 分 支 然 后 选 择 主 分 支   / d o c s   目 录 ， 将 其 设 置 为   G i t H u b   P a g e s   的 源   ， 点 击 保 存 ， 你 就 搞 定 了 。 G i t H u b   P a g e s   将 会 从 你 的   / d o c s   目 录 中 读 取 内 容 ， 转 换   i n d e x . m d   为   H T M L 。 然 后 把 它 发 布 到 你 的   G i t H u b   P a g e s   的   U R L   上 。 这 样 将 会 创 建 并 输 出 一 个 最 基 础 的   H T M L   ， 而 且 你 可 以 使 用   J e k y l l   的 自 定 义 模 板 、 C S S   和 其 他 特 性 。 如 果 想 要 看 所 有 的 可 能 ， 你 可 以 看 看   G i t H u b   P a g e s   S h o w c a s e [ 5 ] 。 v i a :   h t t p s : / / g i t h u b . c o m / b l o g / 2 2 3 3 - p u b l i s h - y o u r - p r o j e c t - d o c u m e n t a t i o n - w i t h - g i t h u b - p a g e s 作 者 ： l o r a n a l l e n s m i t h   [ 6 ]   译 者 ： B e s t o n y [ 7 ]   校 对 ： w x y [ 8 ] 本 文 由   L C T T [ 9 ]   原 创 编 译 ， L i n u x 中 国 [ 1 0 ]   荣 誉 推 出 [ 1 ] :   h t t p s : / / w w w . y o u t u b e . c o m / w a t c h ? v = 2 M s N 8 g p T 6 j Y [ 2 ] :   h t t p s : / / w w w . y o u t u b e . c o m / w a t c h ? v = R a K X 4 A 5 E i Q o [ 3 ] :   h t t p s : / / h e l p . g i t h u b . c o m / a r t i c l e s / c o n f i g u r i n g - a - p u b l i s h i n g - s o u r c e - f o r - g i t h u b - p a g e s / [ 4 ] :   h t t p s : / / p a g e s . g i t h u b . c o m / [ 5 ] :   h t t p s : / / g i t h u b . c o m / s h o w c a s e s / g i t h u b - p a g e s - e x a m p l e s [ 6 ] :   h t t p s : / / g i t h u b . c o m / l o r a n a l l e n s m i t h [ 7 ] :   h t t p s : / / g i t h u b . c o m / b e s t o n y [ 8 ] :   h t t p s : / / g i t h u b . c o m / w x y [ 9 ] :   h t t p s : / / g i t h u b . c o m / L C T T / T r a n s l a t e P r o j e c t [ 1 0 ] :   h t t p s : / / l i n u x . c n / 推 荐 文 章 推 荐 文 章 点 击 标 题 或 输 入 文 章   I D   直 达 该 文 章
点 击 标 题 或 输 入 文 章   I D   直 达 该 文 章 将 文 章 分 享 给 朋 友 是 对 我 们 最 好 的 赞 赏 ！ 阅 读 原 文
回复

举报

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

使用Markdown编辑器编辑 使用富文本编辑器编辑

Archiver| 手机版| 小黑屋|
Powered by Discuz! X3.4 Copyright © 2001-2020, Tencent Cloud. 商业源码建议获取授权，如侵犯您的权益，请联系客服处理