Nodejs 如何使用gulp来把markdown生成html文档并上传到git pages上

Nodejs 如何使用gulp来把markdown生成html文档并上传到git pages上

gulp-gh-pages插件教程

perlican里用到py写的ghp-import命令

ghp-import是Easily import docs to your gh-pages branch的工具。

那么nodejs里有没有呢？我找到2个

可选项

例子

这里我们举一个例子，把README.md编译成html，并带有左侧目录功能，然后推送到git pages上。

为什么要这样做呢？

  1. markdown编写文档非常方便
  2. md生成html的时候没有目录导航，所以需要i5ting_ztree_toc插件
  3. git pages是免费的http静态服务器，放文档或博客等静态网页再合适不过了

使用gulp

npm install --save-dev gulp
npm install --save-dev gulp-gh-pages

并创建gulpfile.js文件，见本仓库根目录

如果你不熟悉gulp，可以再这里https://github.com/i5ting/js-tools-best-practice/blob/master/doc/Gulp.md学习

3个步骤

1、task ‘generate’

把README.md编译成html，并带有左侧目录功能。

这里使用tocmd命令（tocmd 是一个ruby gem，用于把markdown文件生成带有toc目录的html文档。）

tocmd_conf -f README.md

如果你本机没有安装的话，可以根据https://github.com/i5ting/tocmd.gem里的文档里安装方法

gem intall tocmd

前提是你一定要ruby2.0以上的环境哦。

2、task ‘rename’

这步主要是，上一步生成的文件是README.md，而静态网站使用的是index.html，所以需要重命名。 这里简单的把./preview/README.html文件复制为./preview/index.html

cp ./preview/README.html ./preview/index.html

3、task ‘deploy’

把./preview/**/*目录的内容推送到git仓库的gh-pages分支上。

核心代码

这里主要使用gulp-gh-pages插件，它是会把指定目录的内容推送到git仓库的gh-pages分支上。 利用git pages静态http server的特性可快速建立网站。

var gp_deploy = require('gulp-gh-pages');

var options = {}
gulp.task(‘deploy’, function () {
return gulp.src(’./preview/**/*’)
.pipe(gp_deploy(options));
});

如果想了解更多配置，见https://github.com/rowoot/gulp-gh-pages

测试

执行gulp命令，结果如下：

	➜  gp-pages-import-test git:(master) gulp
	[22:15:16] Using gulpfile ~/workspace/github/gp-pages-import-test/gulpfile.js
	[22:15:16] Starting 'generate'...
	cp: img: No such file or directory
	src path = /Users/sang/workspace/github/gp-pages-import-test
	desc path = /Users/sang/workspace/github/gp-pages-import-test/preview
	"start building......"
	"process_with_one"
	"build = /Users/sang/workspace/github/gp-pages-import-test/preview/README.html"
	"0.4.1"
	[22:15:17] Finished 'generate' after 725 ms
	[22:15:17] Starting 'rename'...
	[22:15:17] Finished 'rename' after 127 ms
	[22:15:17] Starting 'deploy'...
	[22:15:17] [gulp-gh-pages]: Cloning repo
	[22:15:17] [gulp-gh-pages]: Checkout branch `gh-pages`
	[22:15:18] [gulp-gh-pages]: Copying files to repository
	[22:15:18] [gulp-gh-pages]: Adding 2 files.
	[22:15:18] [gulp-gh-pages]: Commiting "Update 2014-11-13T14:15:17.666Z"
	[22:15:18] [gulp-gh-pages]: Pushing to remote.
	[22:15:30] Finished 'deploy' after 13 s
	[22:15:30] Starting 'default'...
	default
	[22:15:30] Finished 'default' after 27 μs

然后访问 http://i5ting.github.io/gp-pages-import-test/ 即可理解看到效果

注意：gh-pages第一次推送上去的时候需要大约10分钟左右的时间部署的。以后就实时更新了。

原理

下面给出手动操作gh-pages分支的做法，非常繁琐

git checkout --orphan gh-pages
git rm -rf .
touch README.md
git add README.md
git commit -m "Init gh-pages"
git push --set-upstream origin gh-pages
git checkout master

实际上gulp-gh-pages插件把这些操作都封装到代码了。

说的就这么简单，但实际里面判断的逻辑非常复杂，有兴趣的朋友自己看吧。

源码

总结

使用gulp作为作业管理非常棒，可以方便的集成shell，命令以及nodejs脚本，还有gulp自己的插件。

像gulp-gh-pages插件，在我们平时编写文档的过程中方便了好多。

希望有更多人能够学会这种技术


6 回复

Nodejs 如何使用gulp来把markdown生成html文档并上传到git pages上

概述

本文将介绍如何使用Node.js和Gulp来将Markdown文件转换为HTML，并通过Git Pages进行发布。我们将使用gulp-gh-pages插件来处理GitHub Pages的部署工作。

安装依赖

首先，确保你已经安装了Node.js和npm。接着安装必要的Gulp插件：

npm install --save-dev gulp
npm install --save-dev gulp-gh-pages

创建Gulp任务

接下来，我们需要创建一个gulpfile.js文件来定义一些Gulp任务。

const gulp = require('gulp');
const gp_gh_pages = require('gulp-gh-pages');
const markdown = require('gulp-markdown');
const rename = require('gulp-rename');

// 任务1：生成HTML
gulp.task('generate', function() {
    return gulp.src('./src/README.md')
        .pipe(markdown())
        .pipe(rename('index.html'))
        .pipe(gulp.dest('./dist'));
});

// 任务2：部署到Git Pages
gulp.task('deploy', function() {
    return gulp.src('./dist/**/*')
        .pipe(gp_gh_pages());
});

// 默认任务
gulp.task('default', gulp.series('generate', 'deploy'));

详细说明

  1. 生成HTML：

    • 使用gulp-markdown插件将Markdown文件转换为HTML。
    • 使用gulp-rename插件将输出文件重命名为index.html。
    • 将生成的HTML文件保存到dist目录中。

  2. 部署到Git Pages：

    • 使用gulp-gh-pages插件将dist目录中的所有文件推送到GitHub Pages分支。

执行Gulp任务

运行以下命令来执行Gulp任务：

gulp

注意事项

  • 确保你的GitHub仓库已经设置了GitHub Pages分支（通常是gh-pages）。
  • 如果你是第一次部署，可能需要几分钟时间才能看到更新后的页面。

总结

通过上述步骤，你可以轻松地将Markdown文件转换为HTML，并通过Gulp自动化部署到GitHub Pages。这种方法不仅简化了文档的生成和发布流程，还提高了开发效率。希望这篇教程对你有所帮助！


还有更简单的做法，使用docto

docto

docto is a Doc Tool for Generate README.md with Toc and Push it to Git Pages

npm version

Features

  • 基于nodejs写的，安装简单
  • 基于gulp构建，简单易用
  • 子项目里无需安装gulp和依赖模块，即可使用
  • 初始化README.md
  • 自动编译成html
  • 自动有基于ztree的toc目录
  • 自动发布到git pages

Install

npm install -g docto

Usages

1）指定用户和项目

docto i5ting/docto

实例

初始化git仓库

git clone git@github.com:i5ting/docto-example.git

创建README.md

docto i5ting/docto-example

查看gulp的tasks

➜  docto-example git:(master) ✗ gulp -T
[20:56:41] Using gulpfile ~/workspace/github/docto-example/gulpfile.js
[20:56:41] Tasks for ~/workspace/github/docto-example/gulpfile.js
[20:56:41] ├── deploy
[20:56:41] ├── rename
[20:56:41] ├── copy_img
[20:56:41] ├─┬ doc
[20:56:41] │ └── copy_img
[20:56:41] ├─┬ show
[20:56:41] │ └── doc
[20:56:41] └─┬ default
[20:56:41]   ├── doc
[20:56:41]   ├── rename
[20:56:41]   └── deploy

生成文档

gulp doc

推送到git pages

gulp deploy

默认任务

gulp
  • 编译README.md为preview/README.html
  • 修改preview/README.html为preview/index.html
  • 推送到git pages

以后麻麻再也不担心我写README了

实例图

Screen Shot 2015-10-24 at 9.59.42 PM.png

先马再看

来自炫酷的 CNodeMD

要将Markdown文件转换为HTML并自动部署到Git Pages上，你可以使用gulp配合gulp-gh-pages插件。下面是如何实现的简明步骤。

安装必要的依赖

首先，你需要安装gulp和gulp-gh-pages：

npm install --save-dev gulp gulp-gh-pages

接着安装marked库来处理Markdown转HTML：

npm install --save marked

创建Gulp任务

在项目根目录下创建一个gulpfile.js文件，并添加以下内容：

const gulp = require('gulp');
const ghp = require('gulp-gh-pages');
const marked = require('marked');

// 生成HTML
function generateHtml() {
    const markdownContent = `
# Welcome to My Markdown Page

This is a simple markdown example.
`;
    const htmlContent = marked(markdownContent);
    // 假设有一个文件系统模块来写入文件
    require('fs').writeFileSync('preview/index.html', htmlContent);
}

// 部署到Git Pages
function deployToGitPages() {
    return gulp.src('./preview/**/*')
        .pipe(ghp());
}

// 注册任务
gulp.task('generate', generateHtml);
gulp.task('deploy', deployToGitPages);
gulp.task('default', gulp.series('generate', 'deploy'));

运行Gulp任务

运行以下命令以执行上述任务：

gulp

这段代码将执行两个主要步骤：首先，将Markdown转换为HTML；然后，将生成的HTML文件部署到Git Pages。确保你的GitHub仓库已经设置好可以接受来自gh-pages分支的提交。

以上就是如何使用Node.js中的Gulp将Markdown文件转换为HTML，并部署到Git Pages的基本步骤。

回到顶部