Shrimple – 一种更简单、更优雅的 Markdown

# 一个更好、更简洁的 Markdown 替代方案。 来源：https://qount25.dev/Shrimple/ ## Shrimple 一个**更好**、**更简洁**的 Markdown 替代方案。获取它 (https://code.qount25.dev/qount25/Shrimple)。 这是一份 Shrimple 文档。它以这样的方式编写，使得它看起来既整洁又易读——无论是作为纯文本文档，还是渲染成 HTML 时。 ## 安装与使用 你需要先安装 Go 编译器来编译它： `` go build `` 然后这样运行： `` cat README | ./shrimple -s -w > README.html `` `-s` 或 `--default-css` 标志为 HTML 输出添加默认的 CSS，而 `-w` 或 `--wrap` 标志将页面包裹在 HTML 中，构成一份完整的文档。如果你希望生成输出并以某种方式插入到自己的网站中，那么你不需要使用这些标志。 查看所有可用选项，请输入：`./shrimple --help` ## 链接与脚注 链接也设计得简洁美观。我们不会用内联 URL（可能很长且破坏可读性）污染源文档，而是采用一个非常**简洁**！（https://shrimple.qount25.dev/）的想法：链接从其引用的脚注中获取 URL。 当然，你也可以添加一个常规脚注1 (https://qount25.dev/Shrimple/#footnote_1)，此时词语旁边带数字的小链接会将你引向脚注部分。 ## 代码 让我们从代码块开始。请看下面的例子：即使两个 `if` 块之间有一个空行，它们仍然会构成一个单独的代码块： `` if err != nil { return -1 } if err == nil { return 1 } `` 代码块必须缩进 6 个空格，渲染时这 6 个空格会被去除，但之后多余的空格会保留。代码块的第一行（以 `### Go` 开头）是可选的，但它会为代码块标签添加一个 HTML 类——当与 Prism.js (https://prismjs.com/) 代码高亮器一起使用时，会对特定语言进行正确的代码高亮。 我们也可以使用内联代码，例如 `fmt.Println("this is inline code")`。 ## 列表 Shrimple 也允许你创建编号列表和项目符号列表。例如，这是一个项目符号列表： - 列表必须向右缩进两个空格。 - 每个项目可以与前一个项目之间用空行隔开，也可以不隔开。 - 如果列表项很长，你可以轻松地将内容放在下一行。在这种情况下，后续行必须缩进 4 个空格，以便与第一行对齐。 非常类似的是编号列表： 1. 缩进相同——两个空格。 2. 后续项目可以正常编号（不像 Markdown 中必须全部为“1”）。 3. 任何编号列表项中的后续行必须与第一行上的句点字符“.”对齐。 4. 数字不必连续，但它们会被标准化为连续。它就这样*生效了！* ## 两种标题类型 标题允许有两种级别：“h1”和“h2”。级别由下划线的“粗细”决定，其中 `===` 表示“h1”，`---` 表示“h2”。关于标题的一个重要事项：无论时间如何，标题下面的一行必须至少为 3 个字符（这是一个硬编码规则），否则上面的行将不会渲染为标题。 ## 注释 注释以一行全大写单词（无空格）开头，可选地后跟任何标点符号——在本例中是“:”。后续行必须缩进 4 个空格。单词不必是“NOTES”，也可以是“SIDENOTE”或“ATTENTION”。该单词本身会被转换为小写，并在输出中用作 HTML 标签的 CSS 类。 注释也可以包含空行（无缩进），但空行必须被属于该注释的非空行（因此缩进 4 个空格）包围，才能被视为注释的一部分。 ## 解析与渲染字典 这是 Shrimple 最强大的功能之一。你无需用各种奇怪的字符或 HTML 污染原始文档，只需编写文本，当需要突出显示某些单词或表达式的出现时，你通过定义解析与渲染字典来实现。请查看存储库根目录中的两个文件：`parse_dict` 和 `render_dict`，然后看下一段中的例子： 这一段是解析和渲染字典的一个例子。注意 word1 和 word2 带有下划线，而 word3 和 expression with some spaces in it 显示为绿色。但在源 Shrimple 文档中，这些单词没有额外的标记。它们只是根据解析和渲染字典被识别出来的。 要指示 Shrimple 使用解析和渲染字典，请使用 `-p` 和 `-r` 命令行参数（“p”代表解析，“r”代表渲染）： `` ./shrimple ... -p path/to/parse_dict -r path/to/render_dict `` ## 生成静态网站 Shrimple 的目标之一始终是能够生成文档页面。这通过 Shrimple 的静态网站生成器得以实现。它会接受一个源文件目录（使用 Shrimple 格式编写），将每个文件转换为 HTML 文档，并将所有文件输出到另一个目录。每个页面可选地包含一个菜单以及底部的上一页/下一页导航链接。 让我们看看它是如何工作的。假设你有以下目录结构： `` StaticSite | '-- StaticSite | 1_Part_One | | | 001_chapter_one | 002_chapter_two | 003_chapter_three | 2_Part_Two | | | 001_chapter_four | 002_chapter_five | 3_chapter_six | 4_chapter_seven `` 条目 `1_Part_One` 和 `2_Part_Two` 是目录。其余的是文件。当文件与其所在目录同名时，在生成静态网站后它将变成 `index.html`。目录和文件名开头的数字用于确保正确的顺序，这对于能够生成导航和菜单链接是必要的。 为方便起见，`examples/StaticSite` 目录中提供了相同的文件结构。要生成静态网站，请使用以下命令： `` ./shrimple -s -g -n -m examples/StaticSite StaticSite_out `` 然后查看 `StaticSite_out` 目录中的内容。如果对某些文件进行了更改，然后再次运行相同的命令，Shrimple 将只生成需要重新生成的文件。 提供的选项如下： - `-g` 或 `--generate-site` 告诉 Shrimple 我们要从源目录生成静态网站。 - `-s` 你已经知道——它添加一个默认样式表，但你也可以用 `-c` 或 `--css` 指定自定义样式表。 - `-n` 告诉静态网站生成器在每页底部添加上一页/下一页导航链接。 - `-m` 还会添加一个嵌套良好的菜单，包含指向所有生成页面的链接。 菜单和导航中的所有链接在你通过浏览器中的“文件 - 打开”直接打开页面时也能工作，不需要服务器。 ## 脚注 1. 脚注基本上是编号列表项。 2. 不过你可以在文档中的任何位置通过放置 [n] 来引用它们（见上文）。 3. 或者你可以用它们创建链接，而不污染文档本身，方法是写上 '-> link [4]'。 4. https://shrimple.qount25.dev 5. https://prismjs.com 6. https://code.qount25.dev/qount25/Shrimple