实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播

最新推荐文章于 2024-06-18 00:24:32 发布
最新推荐文章于 2024-06-18 00:24:32 发布
阅读量925 收藏 2
点赞数
文章标签： 技术写作 技术传播 技术文档 开源社区 GitHub
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/BGRichi/article/details/104026446
版权

前段时间有幸参与了开源社区的活动，并且借由 Apache Pulsar 项目实践了 GitHub + MarkDown 的文档开发。在与开源社区的童鞋进行交流的过程中了解到，对于非技术专业的TCer，即便对于社区贡献具有热情，但往往会被看似复杂的工具和流程“劝退”。那么在这里，我会基于个人的实践与体验，分享一下自认为“最简”的操作说明。

在本文中，会按照以下顺序进行介绍：

  1. 整体流程及难点说明：概览整体流程，并且指出操作难点。

  2. 预备知识和准备工作：在部署和使用 GitHub + MarkDown 进行文档开发的过程中，需要掌握的基础知识，及准备工作。

  3. 操作界面说明：整体流程涉及的操作界面简介。

  4. 工作环境部署说明：将本地电脑部署为参与开源项目的终端。通常，在项目存续过程中，工作环境仅需部署一次；如工作环境损坏，可直接删除本地文件后，进行重新部署。

  5. 日常工作流程说明：在工作环境已部署的情况下，每一轮修改，都需要完整执行日常工作流程，实现闭环。

那么接下来，就让我们具体看看。

整体流程及难点说明

整体流程

从整体来看，使用 GitHub + MarkDown 参与开源项目主要包括以下步骤：

图片说明：

  • 实线：操作步骤及数据方向。

  • 序号：操作步骤。

  • 虚线上方：GitHub 云端操作。

  • 虚线下方：本地操作。

  • 虚线切割：线上/线下传输操作。

  1. fork：创建备份，将 apache/pulsar 目录复制为个人  <user>/pulsar 目录。后续针 pulsar 项目的修改基于个人目录实施。

  2. clone：复制个人 <user>/pulsar 目录的项目文件下载到本地。

  3. fetch upstream：建立本地文件与 apache/pulsar 的同步更新，确保后续使用最新版本文件进行修改。

  4. branch：创建修改分支。

  5. edit：使用编辑工具修改文件内容。

  6. commit：文件修改完成后，提交文件。

  7. push：上传文件至个人 <user>/pulsar 目录。

  8. pull request：提交修改 PR 至 apache/pulsar，待确认无误后合入 apache/pulsar。

其中：1～3为工作环境部署；4～8为修改流程。后续将在“工作环境部署说明”和“日常工作流程说明”2个部分进行详细说明。

难点说明

  1. 工作环境部署涉及较多命令行操作，对于非技术用户可能不是特别友好，如果有条件，不妨请技术小伙伴协助完成；不过如果尝试独立完成，一定会获得满满的成就感，相信你可以的。

  2. 在日常工作中，需要特别注意文件的版本控制，避免在提交 pull request 时，出现混淆。具体说明参见：日常工作流程说明 > 1. branch

预备知识和准备工作

在进行后续操作说明时涉及以下内容，但不会展开说明，需要大家预先了解。

    1. 在进行工作环境部署时，涉及命令行操作。需了解：

  • 如何调出命令行对话框。

  • 如何使用 DOS 命令定位至指定目录。相关命令包括：cd, cd.., cd\, <盘符>, cd <目录>,dir

    2. 注册 GitHub 用户。

 链接：https://github.com/join


   3. 安装 GitHub 桌面版。

 链接：https://desktop.github.com/

操作界面说明

在所有操作过程中，涉及以下三种界面：

  • GitHub 的 Web 页面：用于 GitHub 云端操作。例如：fork、pull request 等。

  • 命令行页面：推荐用于工作环境部署。

  • GitHub 桌面版：推荐用于日常工作流程。

GitHub 的 Web 页面

命令行页面

GitHub 桌面版

准备好了吗？下面我们就要正式进入操作流程了，祝你好运！

工作环境部署说明

工作环境部署操作包括：

  1. fork：创建备份，将 apache/pulsar 目录复制为个人  <user>/pulsar 目录。后续针对 pulsar 项目的修改基于个人目录实施。

  2. clone：复制个人 <user>/pulsar 目录的项目文件下载到本地。

  3. fetch upstream：建立本地文件与 apache/pulsar 的同步更新，确保后续使用最新版本文件进行修改。

1. fork

操作界面：GitHub 的 Web 页面

    1） 访问 apache/pulsar 项目页面：
          链接：https://github.com/apache/pulsar
 

    2） 点击 fork 按钮。

fork 操作完成后， apache/pulsar 和 <user>/pulsar 被加入至本人的 Repositories 表。

2. clone

操作界面：GitHub 桌面版

    1） 点击 Current repository > Add > Clone repository，打开 Clone a repository 对话框。

    2） 在 Clone a repository 对话框：
          指定 Your repository 为 <user>/pulsar；
          指定 Local path 为指定本地目录；
          点击 Clone 按钮。

clone 操作完成后，<user>/pulsar 的项目文件下载至本地指定目录。

3. fetch upstream

操作界面：命令行

    1） 调出系统命令行操作界面。

说明：由于不同系统调出系统命令行操作界面的方法不同，请自行搜索解决。本文以 Window 10 操作系统为例：

          点击“开始” > “搜索”按钮；

          搜索“cmd”，打开“命令提示符”窗口。

    2） 使用 DOS 命令定位至工作目录路径。例如：

D:\myFolder\PULSAR\Repository\pulsar>

    3） 在工作路径下，依次执行以下命令：

#设置本地文件与 apache/pulsar 同步#
git remote add upstream https://github.com/apache/pulsar.git

#验证同步设置#
git remote -v

#正确返回信息#
origin    https://github.com/$user/pulsar.git (fetch)
origin    https://github.com/$user/pulsar.git (push)
upstream  https://github.com/apache/pulsar (fetch)
upstream  https://github.com/apache/pulsar (push)

#设置本地master分支同步#
git checkout master
git fetch upstream
git rebase upstream/master
git push origin master

祝贺你，你已经成功完成了本地工作环境部署。

日常工作流程说明

每次实施修改，都要按照日常工作流程操作闭环，具体内容包括：

  1. branch：创建修改分支。
    注意：
    1) 一个 issue 对应一个 branch。
    2) 每次修改必须创建修改分支，不可在 master 分支上直接实施修改。

  2. edit：使用编辑工具修改文件内容。

  3. commit：文件修改完成后，提交文件。
    注意：提交文件时，需确认提交到正确的修改分支。

  4. push：上传文件至个人 <user>/pulsar 目录。

  5. pull request：提交修改 PR 至 apache/pulsar，待确认无误后合入 apache/pulsar。

日常工作流程推荐非技术用户使用 GitHub 桌面版进行操作，更加友好易用，让我们来看看吧。

1. branch

1）设置 Current repository 为 <user>/pulsar；

2）点击 Current branch > New branch，打开 Create a branch 对话框。

3）在 Create a branch 对话框：

        输入修改分支的名称，例如：wldtest；

        指定修改分支基于的分支，默认为 master；

        点击 Create branch。

branch 操作完成后，点击 Current branch，从列表中查询并切换至新建分支。

2. edit

打开已下载至本地的工作目录，使用适当的 MarkDown 工具，编辑项目文件。文件修改后，GitHub 桌面版自动识别并显示变更。

3. commit

确认修改无误后，填写变更说明，点击 Commit to <branch name>，提交本轮修改。

注意：提交文件时，需确认提交到正确的修改分支。

4. push

最后点击 push origin，将文件上传到 GitHub 的个人 <user>/pulsar。

5. pull request

点击 Create Pull Request，跳转到 GitHub 的 Web 页面，填写相关内容。

在 Pull Request 页面，细心如你一定注意到系统自动添加了下面这条合并信息，即请求由 <user>/pulsar 的修改分支，合并到 apache/pulsar 的 master 分支。一旦修改内容确认无误，就成功完成本轮贡献了。

现在，你已经成为一名开源项目的 Contributor，给自己一些掌声吧。

 

在多人团队开发过程中，良好的工作环境和工作流程（项目管理），有利于进行高效协作。付出额外的学习成本，掌握相关工具和流程是非常有必要的。如果这篇文章恰好能够解决你的困惑，让你的学习过程变得容易了一点点，那就太好了。

相关文章：

实施：UI国际化的坑，都踩明白了吗 | 技术传播

实施：Word样式协同共享，降低文档开发成本 | 技术传播

实施：同源下发，保证内容一致性 | 技术传播

其他推荐：

企业级信息管理系统初创方案构思 | 技术传播

技术传播是一片蓝海 | 技术传播

访谈：TC无处不在，只是我们没有发觉 | 技术传播

这次他们说好要“讲真的” | 传播

在座都别吵了，你们还有我 | 技术传播

一本培养强迫症患者的说明书 | 技术传播

就像用心做好日本料理 | 技术传播

顽固的老头子与无聊的说明书 | 技术传播

转战新媒体 | 技术传播

评测：王者荣耀的用户帮助系统 | 技术传播

让爸爸妈妈也能享受到科技发展带来的便利 | 技术传播

 

 

公众号：techcomm / htstory

微信号：bgrichi

邮箱：hash_0813@163.com

睿齐
关注
  • 0
    点赞
  • 踩
  • 2
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
使用Swagger2Markup实现API文档的静态部署（二）：Markdown和Confluence
程序猿DD
01-29 1455
在上一篇《使用Swagger2Markup实现API文档的静态部署（一）：AsciiDoc》中，我们介绍了如何使用 Swagger2Markup将Swagger文档转换成AsciiDoc，再将AsciiDoc转换成静态HTML。下面，本文将继续介绍Swagger2Markup可以转换的另外两个格式：Markdown和Confluence。Swagger2Markup简介Swagger2Markup
markdown转HTML并自动部署开机启动
08-10
将markdown文本转化为html并部署在本地，自动转化文件夹下markdown并监控更新，通过localhost:3000/api/{filename}访问
Markdown基本配置与使用
m0_74423718的博客
06-18 288
它使用简单易懂的语法规则，使得文本在保持可读性的同时，可以快速转换为HTML等格式。
你会用 markdown ，那你会部署文档网站吗
weixin_43487782的博客
10-10 1131
相信大家平时都会用 markdown 编写文档，特别是配合 Typora 使用非常方便。但很多时候我们不满足于本地文档，而是要把文档做成在线的形式，这样如果内容更新，团队成员都可以及时看到。 那么其实用来生成静态网站的开源项目也有不少，例如 VuePress ，Docsify 等，特别是 VuePress 已经广泛用于 Vue 官方文档在内的各种文档的部署。但是 VuePress 是基于 Vue 的，而本人现在团队主要使用 React 技术栈，于是采用了和 VuePress 类似的由 facebook 团队
本地 MarkDown 怎么部署到服务器上？教你使用 Docsify 搭建个人博客
热门推荐
寒泉
12-29 7万+
使用Docsify搭建文档类型网站 docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是，它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档并直接部署在 GitHub Pages。 Docsify官方文档：https://docsify.js.org/#/zh-cn/ 安装 docsify-cli 工具 推荐全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。
公司搭建环境技术文档集锦
12-17
在公司找到了一些平时搭建环境的文档，放到一下，以备以后去使用，有关于linux服务器环境的搭建、oracle环境的搭建、weblogic环境的搭建、weblogic应用的部署等各大流程。非常专业的文档。那出来与对环境搭建不熟练的人进行分享。
营造健康社区：GitHub行为准则(Code of Conduct)的实践指南
最新发布
07-24
- **GitHub Actions**：支持自动化工作流程，如自动运行测试、部署代码等。 - **GitHub Pages**：允许用户免费托管静态网站，用于展示项目文档或个人作品集。 - **私有仓库**：用户可以创建私有仓库，以控制特定代码...
rtp：用于存储和增强用于工作的脚本的存储库
02-09
【rtp：用于存储和增强用于工作的脚本的...综上所述，`rtp`是一个旨在提升团队协作和代码质量的工具集，它利用了Jupyter Notebook的强大功能，结合版本控制、脚本优化和工作流程管理，为IT项目提供了高效的工作环境。
ainsuasty:博客Rrstudio +雨果+ LoveIt
03-29
Rmarkdown是一种文档格式，允许用户混合文本、代码和结果，特别适合数据科学家和统计学者分享他们的工作流程和发现。 其次，雨果（Hugo）是一个快速且高效的静态网站生成器，适用于构建博客和其他类型的网站。与...
maas-docs:MAAS的文档
05-25
该文档采用 **GitHub Flavored Markdown (GFM)** 编写，这是一种Markdown语言的变体，增加了如表格、任务列表和内联图片等特性，使文档更具可读性和格式化效果。编译后的文档会转换成 **HTML** 格式，HTML是一种广泛...
covid19-repo-recommender：通过MLFlow部署模型，该模型根据编程语言和关键字推荐与GitHub Covid19相关的GitHub仓库
02-01
项目中涉及的Jupyter Notebook是数据科学家常用的交互式开发环境，它允许用户编写和运行Python代码，同时结合Markdown文档，方便地展示分析过程和结果。在"COVID-19JupyterNotebook"这个标签中，我们可以推断项目...
关于部署方面的相关知识点
weixin_47268710的博客
12-17 404
为了解决HTTP协议的这一缺陷，需要使用另一种协议：安全套接字层超文本传输协议HTTPS，为了数据传输的安全，HTTPS在HTTP的基础上加入了SSL/TLS协议，SSL/TLS依靠证书来验证服务器的身份，并为浏览器和服务器之间的通信加密。这就是HTTP和HTTPS的最大区别。一直以来HTTP协议都是最主流的网页协议，HTTP协议被用于在Web浏览器和网站服务器之间传递信息，以明文方式发送内容，不提供任何方式的数据加密，如果攻击者截取了Web浏览器和网站服务器之间的传输报文，就可以直接读懂其中的信息。
利用Git进行docx文档版本管理的简单方法
Do more, know more, be more.
03-16 6564
需求： 1）程序开发过程中，不同代码版本的管理 2）论文/技术文档（docx）写作过程中，不同文档版本的管理 3）最好能跨平台（win,mac）使用 解决方法 概要步骤： 1）安装与设置Git，创建版本库（repository） 2）安装Pandoc，配置Git以能管理Microsoft Word的docx文件。 Git是目前最棒的分布式版本控制软件，有很多非常实用的功能，比如： 跟踪文...
【hexo】免费使用github搭建Markdown博客系统
XYZ
10-01 7952
本篇博客向大家介绍一下Markdown博客系统的搭建。关于搭建博客的具体细节大部分内容参考于：使用hexo+github搭建免费个人博客详细教程。笔者亲自尝试后，又做了一点补充，应该能够让大家很容易地学会如何利用hexo做一个博客系统。首先，给出效果：https://jack13163.github.io/。 目录 1. markdown简介 1.1markdown是什么? 1...
开源应用中心|如何快速部署你的绝佳Markdown写作平台——CodiMD
DNSPod
05-07 1290
前言在如今这个知识创作盛行的时代，大家可能想将自己的所思、所学记录并分享出去，那么寻找一款合适的写作平台就是比较重要了。Markdown格式自问世以来，以其简单和优雅的语法吸引了大量的用户...
内网穿透的应用-本地部署Stackedit Markdown编辑器公网远程访问
weixin_42878111的博客
10-09 317
同时,StackEdit 是开源的,个人可以本地部署自己的Markdown编辑器,并且通过浏览器即可快速访问.当然,本地访问局限性太大,结合cpolar 内网穿透工具,即可实现远程,随时随地,任意浏览器访问我们部署在本地的Markdown编辑器,提高生产效率!上面以docker方式成功部署和启动运行了属于个人的Markdown编辑器,现在打开浏览器,局域网访问容器挂载的8080端口,然后点击界面顶部开始写作,即可看到我们的Markdown编辑器界面,下面我们安装cpolar 内网穿透工具,实现远程访问。
markdown部署网站
woflyoycm的博客
03-24 273
docsify安装与部署markdown网站
文档服务器搭建markdown,服务器部署 - 作业部落 Cmd Markdown 编辑阅读器
weixin_29535577的博客
08-11 705
1.整个项目重新部署:删除原有程序将打包好的ROOT.war包copy到服务器的webapps目录下,执行前需要配置好相关的适用服务器配置文件:WEB-INF下的web.xml文件WEB-INF/classes/文件夹下的数据库配置文件、servlet配置文件等各种项目独有的配置文件程序重新部署以后将服务器上原来的存在的附件还原(通常放在备份下来的webapp下的某个文件夹下)2:部分重新部署:不...
docsify对部署在github上的markdown文档进行加密
09-12
### 回答1： docsify 可以通过一些插件实现对 markdown 文档的加密。具体来说，你需要使用 docsify-encrypt-plugin 插件来实现 markdown 文档的加密。 以下是实现步骤： 1. 在你的项目根目录下安装 docsify-encrypt-plugin 插件： ``` npm install docsify-encrypt-plugin --save-dev ``` 2. 在你的 docsify 项目配置文件中，启用插件并设置密码： ```javascript window.$docsify = { // ... plugins: [ // ... function(hook, vm) { hook.beforeEach(function(content) { return vm.encrypt(content, 'password'); }); } ] }; ``` 在上述代码中，将 password 替换为你自己设置的密码。 3. 在 markdown 文档中，使用以下语法对需要加密的内容进行标记： ``` <!--encrypt 需要加密的内容 --> ``` 例如： ``` <!--encrypt 这是需要加密的内容。 --> ``` 4. 将加密后的 markdown 文档上传到 GitHub 上的仓库中。 现在，其他人在查看该 markdown 文档时，会看到加密后的内容，需要输入密码才能查看解密后的内容。 注意：该插件只能对 markdown 内容进行加密，而无法对图片等其他类型的文件进行加密。 ### 回答2： docsify 是一种用于生成文档网站的工具，它可以将 Markdown 格式的文档直接转化为一个漂亮的网站。然而，docsify 本身并不提供加密功能，也不能直接对在 GitHub 上部署的 Markdown 文档进行加密。 要对在 GitHub 上部署的 Markdown 文档进行加密，可以考虑以下的方法： 1. 使用私有仓库：在 GitHub 上创建一个私有仓库，并将 Markdown 文档放置在私有仓库中。这样只有被授权的用户才能查看和访问这些文档。 2. 使用加密工具：在本地使用加密工具将 Markdown 文档进行加密，然后将加密后的文档上传到 GitHub。这样，只有解密后的文档才能被正确阅读。但是需要注意的是，这种加密方式可能需要事先与阅读者共享解密方法或密码，以确保文档能够被正确解密和阅读。 3. 使用访问控制：在 GitHub 仓库设置中，可以选择限制特定人员或特定团队对仓库的访问权限。通过细粒度的访问控制，可以在 GitHub 上控制谁可以查看和访问 Markdown 文档。 总的来说，将 Markdown 文档进行加密并在 GitHub 上进行部署并不是 docsify 的主要功能。为了保护文档内容的安全性，建议使用 GitHub 提供的访问控制功能或其他专门的加密工具，并与所需的用户进行必要的信息共享和授权。 ### 回答3： docsify是一款非常方便的工具，可以让我们在GitHub上部署Markdown文档并进行加密保护。我们可以使用docsify自带的插件或者第三方的插件来实现加密功能。 首先，我们需要在GitHub上创建一个新的仓库，用于存放我们的Markdown文档和docsify的配置文件。然后，我们将Markdown文档保存在该仓库中的指定文件夹内。 接下来，我们需要在项目的根目录下创建一个名为"_sidebar.md"的文件，用于配置docsify的侧边栏菜单。在该文件中，我们可以指定需要加密的文档，并为其添加密码。 在docsify插件中，有一个名为"docsify-plugin-lock"的插件，可以用于加密文档。我们可以在docsify的配置文件中引入该插件，并进行相关的配置。通过该插件，我们可以为指定的Markdown文档添加密码，并且只有输入正确的密码后才能访问该文档。 除了使用docsify自带的插件外，我们还可以使用第三方的插件来实现文档加密。例如，"docsify-password"插件可以通过设置密码保护整个docsify文档。我们只需要在配置文件中引入该插件，并设置密码即可。 综上所述，我们可以使用docsify及其插件来对部署在GitHub上的Markdown文档进行加密，保护文档内容的安全性。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值