《吴乐川的将 MarkDown 代码转换为 HTML 代码的工具》的针对 Gulpjs 工具链的“包裹”程序

Multilingual Editions of this Article

• English edition of this ReadMe

NPM 页

@wulechuan/gulp-markdown-to-html

源代码仓库

| 提供仓库服务之组织 | 仓库组织之国别 | 仓库地址 | | ------------- | :----------: | ------- | | 码云 | 中华人民共和国 | https://gitee.com/nanchang-wulechuan/wulechuan-js-generate-html-via-markdown-gulp-wrapper.git | | 阿里云之代码仓库 | 中华人民共和国 | https://code.aliyun.com/wulechuan/wulechuan-generate-html-via-markdown-gulp-wrapper.git | | GitHub | 美 | https://github.com/wulechuan/wulechuan-js-generate-html-via-markdown-gulp-wrapper.git |

简介

本工具系对本人另一程序“@wulechuan/generate-html-via-markdown”的“包裹”版本，以令其功能适应 Gulpjs 工具链。

功能亮点

不须带任何参数，即可轻松获得一份华丽的 HTML 文档。其自带精美主题，宽窄屏全自适应排版。包含文章纲要列表，“返回顶部”按钮（实则链接）等等。

亦可通过丰富的参数项，精准控制输出 HTML 之方方面面。从文章纲要列表到“返回顶部”按钮。甚至控制内嵌 CSS 和 Javascript 是否为压缩版本，亦有两个专门的选项。

输出的 HTML 中内嵌样式之来历

本工具默认输出的 HTML 文件在浏览器中呈现时，堪称精美。那么，装点这些 HTML 的样式从哪里来呢？

产生的 HTML 文章中的内嵌样式来源于本人创建和维护的另一项目，即《@wulechuan/css-stylus-markdown-themes》，暂称“项目甲”，亦称“工具甲”。工具甲提供了一组现场的层叠样式表。本工具则选用了甲提供的一款浅色的默认样式。

工具甲之文档集中有若干截图，直观展示一篇文档在应用上述项目自带的两种默认主题样式后之样貌。这两种主题为浅色，另一为深色。见《关于文章排版与配色效果示例集的说明》。

用法

如前所述，本 NPM 包在内部调用另一包（即 “@wulechuan/generate-html-via-markdown”）之功能。并且，本 NPM 包本身并未设计额外的 API（应用编程接口）。因此，要了解使用细节，请参阅完整的《@wulechuan/generate-html-via-markdown 之 应用编程接口》。

示例若干

示例 1

处理假想存在的“我的第一篇markdown文章.md”，不带任何参数，使用默认配置。

const gulp = require('gulp')
const gulpMarkdownToHTML = require('@wulechuan/gulp-markdown-to-html')
module.exports = function myGulpTask1() {
    return gulp.src('./我的第一篇markdown文章.md')
    .pipe(gulpMarkdownToHTML()) // 请留意这一行代码。
    .pipe(gulp.dest('./我的文库'))
}

示例 2

处理一批假想存在的“.md”文件，并通过参数项精准控制输出的 HTML。

const {
    src: gulpRead,
    dest: gulpWrite,
} = require('gulp')

const gulpMarkdownToHTML = require('@wulechuan/gulp-markdown-to-html')

module.exports = function myGulpTask2() {
    return gulpRead('./在你的/计算机中的/某个文件夹内的/文集/**/*.md')
        .pipe(gulpMarkdownToHTML({ // 请留意这一行代码。
            '将Markdown转换为HTML之阶段': {
                '文章纲要列表应采用UL标签而非OL标签': true,

                '针对MarkdownIt生态之诸工具的层叠样式表类名集': {
                    '用于各级标题之超链接A标签的': undefined,
                },
            },

            '对HTML做进一步处理之阶段': {
                '不应注入用于返回文章起始之按钮': true,
                '不应采用任何由本工具内建之层叠样式表': false,
                '产出之HTML文件之HTML标签之语言属性之取值': 'en-US',
            },

            '对本工具现成提供的文章纲要做以下配置': {
                '为求文章纲要列表简洁明了故意仅显示两层条目以至于较深层级条目形同作废': true,

                // 注意： 【呈现文章纲要列表面板】与【展开文章纲要列表的某一条目】并非一回事。
                '浏览器打开HTML文章最初之时文章纲要列表中凡层级深于该值之条目均应收叠': 1,
                '浏览器打开HTML文章最初之时若浏览器窗口足够宽大则直接展开文章纲要列表之面板': true,
            },
        }))
        .pipe(gulpWrite('./在你的/计算机中的/另一个文件夹'))
}

应用编程接口（外国话所谓 API）

本工具适配 Gulpjs 生态，故仅提供唯一的导出体（ export ），且该导出体为默认导出体。该导出体是一个函数，签名（ Signature ）如下：

import type {
    范_将Markdown字符串转换为HTML字符串之转换器之配置项集,
} from '@wulechuan/generate-html-via-markdown'

import type {
    obj as 范_through2_obj,
} from 'through2'

type 范_返回值 = ReturnType<typeof 范_through2_obj>;
declare function _本工具默认导出之函数_临时名称 (
    配置项集: 范_将Markdown字符串转换为HTML字符串之转换器之配置项集
): 范_返回值;

未来计划

暂无。

许可证类型

WTFPL

注意

我未研究过许可证的约束。因此姑且声明为 WTFPL 类型。但实际上该许可证类型可能与我采用的开源模块有冲突。