吴乐川的 HTML 文章排版与配色之方案集

中国人——特别是汉族人，理应坚持广泛、规范地使用汉语。凡非必要之情形不说外国话、不用外国字。此乃天经地义！然则每当必要，亦不排斥采用外国之语言。不妨 博世界之学问，养中国之精神 。

本人亦支持少数民族坚持采用自己民族的传统语言。仍须强调，凡中国人，皆应会用汉语、积极使用汉语，此乃中华各民族之大一统之必由。

Multilingual Editions of this Article

• English version of this ReadMe

NPM 页

NPM 包名

@wulechuan/css-stylus-markdown-themes

作者

南昌吴乐川

此物何用

本工具用于构建一组层叠样式表（即 CSS ）文件，本工具亦现场提供了一组层叠样式表文件。凡这些样式表，均可用于美化采用超文本标记语言（即 HTML ）格式存储的文章。且不必同时取用多个样式表文件，仅取其一足矣。

本品还额外提供了一个很小巧的 JavaScript 接口，使得其它 JavaScript 工具包亦可较方便地以程序化之方式使用这些层叠样式表（ CSS ）文件之内容。详见下文《以程序化之方式取用本工具提供之内容》一节。

于开发者而言，本品亦是一个构件工具，用于相对方便地构建出新的 CSS 文件，以便诸君自定义 HTML 文章之样式。

文档章节

以下章节均存在于单独的文件中，并非本文章之部分。

• 《本工具之简介》
• 《关于文章排版与配色效果示例集的说明（含最终视觉效果）》
• 《本工具构建层叠样式表时所采用之内在规则之介绍》
• 《业已支持的应用场景》
• 《采用本工具开发一套新的文章排版与配色方案之详细步骤》

应用效果示例

一图胜千言。以下各图展示了一篇应用了本工具之默认 CSS 样式的文章之样貌。

以下各图较大，文件大小在 百万字节 级别。

应用默认浅色主题的范文截图

• 示例：简体中文范文配默认浅色主题，在宽大尺寸浏览器中的效果（目录已收叠）
• Snapshot: In default light-colored theme, in a wide window, with toc collapsed

应用默认深色主题的范文截图

• 示例：简体中文范文配默认深色主题，在宽大尺寸浏览器中的效果（目录已收叠）
• Snapshot: In default dark-colored theme, in a wide window, with toc collapsed

范文的所有截图

两篇范文之截图不止于上文中提及的四幅。更多图例，见：

• 《应用效果示例（汉语版）》
• 《Application Examples (en-US)》

另附《示范文章之截图之制作指南》

源代码仓库

使用说明

• 本工具仅提供一组层叠样式表（CSS）文件，及配套的 JavaScript 文件（目前仅一个这样的 JavaScript 文件）。不难理解，本工具并非用于直接将 Markdown 文件转换为对应的 HTML 文件。本工具假定诸君另有方法，将 Markdown 内容转换成 HTML 内容，仅仅是希望借助本工具提供之 CSS 对 HTML 做进一步的排版美化。于此种情形，用法再简单不过——自行取用。

  所谓自行取用，即是说诸君在本项目之发布文件夹中自行找到中意之 CSS 文件（及配套 JavaScript 文件），采用之。且于单一 HTML 文件，在本工具提供之所有 CSS 文件取用其任一足矣，不必取用多者。

  又，取用本工具提供之 CSS 、 JavaScript 文件之内容时，若每每人为复制、粘贴，未免麻烦，且无从实现批量运用、自动化运用。在面对批量运用或自动化运用之要求时，开发人员当然希望能编写程序调集所需资源加以运用。巧了，本工具确实提供了专门的 JavaScript 编程接口，以 JavaScript 字符串 之形式提供各 CSS 、 JavaScript 文件之内容。

  诸君当然可以自行直接取用本工具中之 CSS 文件，或自行调用本工具之 JavaScript 接口。由此二种途径均可以在你构建 HTML 内容时，利用我的这些 CSS 来美化 HTML 内容。然此二种做法均并非易如反掌，更不能一蹴而就。即，要么须费些功夫，要么须专门学习并积累技术经验。

  如若诸君之初衷是要将手头的一些 Markdown 文件转换成 HTML 文件，临用之际单单一个 CSS 文件显然不解诸君燃眉之急。诸君首先需要的是一款可以进行文件格式转换之工具，而后才考虑如何将本工具提供之 CSS 嵌入 HTML 之中，可是？如此，则诸君面临新的问题，即要么无暇自行搭建工具链来将 Markdown 转换成 HTML，要么干脆不知所措。于此种情形，鄙人毛遂自荐，愿助诸君一臂之力！鄙人另行自创有三个 NPM 包，专用于轻松、快速地从 Markdown 内容构建对应之 HTML 内容。且三者均默认采用本工具发布之 CSS 之内容（和配套 JavaScript 内容）。我在本说明书之尾部亦对此三款软件包做了推广。阁下无需另起炉灶了！唯愿三者之任一能对诸君有所裨益！

• 如果阁下取用本工具中之 CSS 主题文件另有意图，即与将 Markdown 转换至 HTML 之事毫无干系，那么或许更应该了解如何编写程序调集所需的由本工具提供之 CSS 资源加以运用。见下文《以程序化之方式取用本工具提供之内容》。

在何处手工取用本工具所生成的文件

取用 CSS 文件

请在 ./源代码/发布的源代码/文章排版与配色方案集/层叠样式表 文件夹下自行获取所需文件。

取用 Javascript 文件

请在 ./源代码/发布的源代码/文章排版与配色方案集/javascript 文件夹下自行获取所需文件。

以程序化之方式取用本工具提供之内容

取用本工具提供之 CSS 、 JavaScript 文件之内容时，若每每人为复制、粘贴，未免麻烦，亦无从实现批量运用、自动化运用。

在面对批量运用或自动化运用之要求时，开发人员当然希望能编写程序调集所需资源加以运用。本工具确实提供了专门的 JavaScript 编程接口，以 JavaScript 字符串数据的形式提供各 CSS 、 JavaScript 文件之内容。

本工具还额外提供了编程接口配套的 TypeScript 类型定义（ index.d.ts ）。

以程序化之方式调用本工具之方法见下例。

下例中代码之主体节选自《测试集/用于测试本项目之-javascript-接口的测试代码集.js》。

const {
    /**
     * 全 13 个接口项如下。
     * 其中 6 个是采用汉语命名的，是新的。
     * 另有 1 个虽也是汉语命名的，但已废弃。
     * 另 6 个是采用外国字命名的，是旧的。
     */

    // 这是一个数组。
    所有已发布之层叠样式表文件之简易描述项之集,

    // 这是一个数组。
    所有已发布之Javascript文件之简易描述项之集,

    // 这是一个对象。
    以文件名称为索引之所有文件简易描述项之字典,

    // 这是一个方法函数，返回一个字符串。
    获取某一已发布之文件之完整内容字符串,

    // 这是一个方法函数，返回一个字符串。
    获取本项目官方选定之所谓默认层叠样式表之完整内容字符串,

    // 这是一个方法函数，返回一个字符串。
    获取本项目官方选定之所谓默认Javascript之完整内容字符串,

    // ------------------------------------------------

    // 已因命名不够明确而废弃（仍可用但不推荐）。
    // 请改用 “ 以文件名称为索引之所有文件简易描述项之字典 ”。
    以文件名称为索引之所有文件之字典,

    // ------------------------------------------------

    // 以下为陈旧的采用外国字命名之诸接口。

    // 这是一个数组，其成员均为简易文件描述对象。
    cssFileEntries,

    // 这是一个数组，其成员均为简易文件描述对象。
    jsFileEntries,

    // 这是一个对象，用于依据【文件名】检索简易文件描述对象。
    allFileEntriesKeyingByFileNames,

    // 这是一个方法函数，返回一个字符串。
    syncGetContentStringOfOneFileEntry,

    // 这是一个方法函数，返回一个字符串。
    syncGetContentStringOfDefaultCSS,

    // 这是一个方法函数，返回一个字符串。
    syncGetContentStringOfDefaultTOCJavascript,
} = require('@wulechuan/css-stylus-markdown-themes') // require 本模块





const 所谓默认层叠样式表文件之内容全文 = 获取本项目官方选定之所谓默认层叠样式表之完整内容字符串()

const 这也是默认层叠样式表文件之内容全文 = 获取某一已发布之文件之完整内容字符串(
    'wulechuan-styles-for-html-via-markdown.default--no-toc.min.css'
)

const 这是针对Typora软件环境的层叠样式表文件之内容全文 = 获取某一已发布之文件之完整内容字符串(
    'wulechuan-styles-for-html-via-markdown--typora.default.css'
)

const 这是第7个层叠样式表文件之内容全文 = 获取某一已发布之文件之完整内容字符串(
    所有已发布之层叠样式表文件之简易描述项之集[6]
)





// 以下演示了三种不同的方法，其任一均可获得默认的并且也是目前唯一的 JavaScript 文件之内容全文。
const 这是所谓默认同时也是目前唯一的Javascript文件之内容全文 = 获取本项目官方选定之所谓默认Javascript之完整内容字符串()

const 这也是目前唯一的Javascript文件之内容全文 = 获取某一已发布之文件之完整内容字符串(
    'table-of-contents-and-back-to-top-anchor-behaviors.min.js'
)

const 这还是目前唯一的Javascript文件之内容全文 = 获取某一已发布之文件之完整内容字符串(
    所有已发布之Javascript文件之简易描述项之集[0]
)

所谓“文件简易描述项”

其 TypeScript 类型定义如下：

declare type 吴乐川用于美化文章的层叠样式表集之数据类型之文件简易描述项 = {
    文件名称: string;
    文件之相对路径: string;
    文件之绝对路径: string;
    文件内容全文: string;
    
    // 以下为陈旧的采用外国字命名之诸接口。

    fileName: string;
    fileRelativePath: string;
    fileAbsolutePath: string;
    fileContent: string;
};

获取本工具发布之各排版与配色方案公用的、且目前唯一的 JavaScript 文件

须知本工具提供两类用途不同之 JavaScript 。

1. 一类是用于注入 HTML 文章以控制 HTML 文章之【纲要】的。
2. 另一类是本工具提供的程序化接口，它并不直接作用于你的任何 HTML，而仅仅是对外提供本 NPM 包之 CSS 以及第一类 JavaScript 。

为方便指代，不妨称第一类 JavaScript 为所谓“文章行为之 js ”，而称第二类 JavaScript 为所谓“本工具接口之 js ”，简称“接口 js ”。

又，获取本工具发布之各色【文章排版与配色方案】公用的、且目前唯一的“文章行为之 js”时，允许对该文件之内容进行些许临时定制。故而，最终获得的内容字符串有异于本工具存储的原始版本。

简而言之，你调用本工具的“接口 js ”中的某接口函数时，可以在接口函数某一项参数传入【配置项集】，以对“文章行为之 js ”之内容做些许定制。

有两个不同的接口函数各自可以接受该配置项集，但形参位置不同。

1. 一个函数是 总接口.获取某一已发布之文件之完整内容字符串 ，它在第 3 形参接受上述配置项集，
2. 另一个函数是 总接口.获取本项目官方选定之所谓默认Javascript之完整内容字符串 ，它在第 2 形参接受上述配置项集。

上述【配置项集】之 TypeScript 类型定义如下：

declare type 吴乐川用于美化文章的层叠样式表集之数据类型之拾取默认Javascript文件之函数之第二参数 = {
    /**
     * 注意：
     * 【展开文章纲要列表面板】与【展开文章纲要列表的某一条目】不是一回事。
     */

    为求文章纲要列表简洁明了故意仅显示两层条目以至于较深层级条目形同作废?: boolean;
    浏览器打开HTML文章最初之时文章纲要列表中凡层级深于该值之条目均应收叠?: boolean;
    浏览器打开HTML文章最初之时若浏览器窗口足够宽大则直接展开文章纲要列表之面板?: boolean;
    
    // 以下为陈旧的采用外国字命名之诸接口。

    shouldShowOnlyTwoLevelsOfTOCItemsAtMost?: boolean;
    atBeginingShouldCollapseAllTOCItemsOfLevelsGreaterThan?: boolean;
    atBeginingShouldExpandTOCWhenWindowIsWideEnough?: boolean;
};

相关推广

鄙人另有一款 NPM 包，名为“@wulechuan/generate-html-via-markdown”。为便于指称，暂将其叫做“甲”。调用甲之接口，可将传入甲的 Markdown 字符串转换成 HTML 字符串。此时，甲默认会采用本工具提供的 CSS 文件来装饰甲自身产生的 HTML 之内容。

鄙人还有一款 NPM 包，名为“@wulechuan/gulp-markdown-to-html”，且作“乙”。乙恰如甲的一个包覆层，使得甲中之功能特性可以适配 Gulpjs 任务流水线。

鄙人还有一款 NPM 包，名为“@wulechuan/markdown-to-html-via-cli”，且作“丙”。丙恰如甲的另一个包覆层，使得任何人在安装丙后（无须另行安装甲），即可在命令行环境轻松使用甲之功能，实现从文件到文件的批量转换。且丙设计有多种命令行参数，以便定制输出之 HTML 之具体细节。且诸君毋需担心命令行参数记忆负担过重之问题，仅需“--help”一招，即可解君之忧。

未来计划

• 避免使用 rem 作为层叠样式表的长度单位，而改用 em ，特别是要避免输出的层叠样式表对 rem 进行配置。理由是倘若本工具产生之层叠样式表如果系用作美化某复杂 Web 应用之局部之文章，本工具提供的层叠样式表不应该粗暴篡改 rem 之取值。

  该项工作已经在进行，全靠业余之投入，截止 2021-03-13 仍未完成。

• 考虑引入更多的 Stylus 变量，来控制主题。但我有疑虑。过分工程化可能反而导致源代码难以理解，不便定制。

• 覆盖 Typora 中“纲要列表”的原有样式？

版本 6 及更旧版本之源代码业已删除

本工具之源代码中故意包括了不少范文截图。这些范文单张尺寸已经不小。何况本工具开发之早期阶段（版本 1 至版本 6）本人频繁调整样式风貌，频繁提交代码。而每每风貌变动，截图亦须重制。这些截图之每一个版本亦虽代码提交至代码仓库（例如“码云”）。久而久之，仓库异常庞大臃肿，累计巨达 600 多百万字节（外国话所谓 MB，不佳之译法所谓“兆字节”）。无奈，本人于 2021 年初彻底抛弃了代码仓库中的旧代码，从头提交了全新的代码。并从那时起极为谨慎的更新范文截图。因此：

1. 旧版代码不复存在。
2. 当前的范文截图常常与代码所能产出之真正面貌有所差异，因为范文更新进度多半时候落后于代码，也落后于 NPM 版本发布。
3. 未来是否因为代码仓库累计尺寸巨大而再次清空代码仓库从头提交代码，亦未可知。

许可证类型

WTFPL

注意：

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