6款免费Markdown (.md) 所见即所得桌面编辑器 – 第一部分

Mark Pelf

5.00/5 (3投票s)

2024年9月15日

CPOL

6分钟阅读

4889

一份实用的Markdown编辑器指南，用于编写GitHub Readme.md文件。

下载源代码

1 忙碌的.NET/C#程序员处理Markdown (.md) 文件

我是一名忙碌的.NET/C#程序员，我决定深入了解一下Markdown标记语言的世界。
我需要不时地创建/维护一些GitHub文档Readme.md文件。和大多数人一样，我一直凭直觉摸索着处理，但我希望提高我的技能/能力，以便更快地产出高质量的文档。鉴于我还在关注许多其他技术，我确信自己对这门因GitHub而流行的标记语言并不特别感兴趣。所以，计划是：

对Markdown (.md) 语言进行一些理论性的概述
学习一些技巧，以便制作花哨的Readme.md文档（例如嵌入图片）
寻找一些免费的Windows桌面所见即所得编辑器，这样我就不必学习/记忆.md语法了
我找到的应用必须是免费的，这样我才能在家里和工作场所使用它们，而没有许可问题。
我想要Windows桌面应用程序，这些应用程序可以相对容易地安装在新机器上。不用过多地折腾Windows Subsystem for Linux (WSL) 或类似的东西。
寻找具有良好GUI/所见即所得功能的编辑器，这样我就不必学习/记忆.md语法，并且能够快速产出体面的文档。

1.1 测试过的Markdown编辑器

以下是经过测试的工具/编辑器

GitHub.com 网站（网站，但作为渲染参考）
Haroopad 编辑器（Windows桌面应用）
Visual Studio Code + 扩展 （Windows桌面应用）
KeenWrite 编辑器（Windows桌面应用）
Zettlr 编辑器（Windows桌面应用）
Texts 编辑器（Windows桌面应用）
Notepad++ + 插件 （Windows桌面应用）

1.2 本系列文章

出于实际考虑，我将把本文分成几篇文章

6款免费Markdown (.md) 所见即所得桌面编辑器 – 第一部分
6款免费Markdown (.md) 所见即所得桌面编辑器 – 第二部分
6款免费Markdown (.md) 所见即所得桌面编辑器 – 第三部分

2 Markdown语言基础知识

一些理论性的方法总是一个好的开始，可以让你更好地理解你所处的环境，并且从长远来看总是能节省你的时间。以下是需要了解的重要内容。

2.1 Markdown语言标准

Markdown只是另一种标记语言。它有它的创始人、历史和工具。维基百科文章[1]对此有详细的解释。

随着时间的推移，它分化成了语言的几种变体/风味。以下是一些：

CommonMark规范 （如[2]中所述）。这实际上被认为是现代Markdown的标准。
GitHub Flavored Markdown Spec （如[3]中所述）。这是GitHub自己的Markdown语言版本。好的一点是，它是CommonMark规范的超集，所以如果你有一个严格“符合CommonMark规范”的编辑器，你制作的所有.md文件都将（应该？）在GitHub网站上正常工作。
markdown-it Variant （基于GitHub上的解析器“markdown-it”实现，位于[4]）。这实际上是GitHub上开源Markdown解析器实现的结果，位于[4]。它遵循CommonMark规范，并添加了语法扩展和快捷方式。

理解Markdown语言存在不同变体/风味这一点很重要，因为你不仅要创建新的.md文件，还需在不同平台上维护现有的.md文件。

所以，为什么有些.md文件在一个平台（桌面、网站等）上工作而在另一个平台上不行，可能仅仅是因为不同的平台支持Markdown语言的不同变体/风味。是的，这可能令人沮丧，但事实就是如此。存在针对不同平台的语法变体。它可能在一个编辑器/网站上渲染良好，而在另一个编辑器/网站上失败。

2.2 “markdown-it variant” vs “CommonMark spec”

为了说明不同变体之间的差异，“markdown-it variant”与“CommonMark spec”，我们将展示来自网站[5]的渲染示例。请注意是否选中了“CommonMark strict”复选框。

这是我们的“Markdown挑战”文件，其中包含了一些语言的非标准特性。

#### MarkdownChallenge1==============
__Advertisement :)__  
(c) (C) (r) (R) (tm) (TM) (p) (P) +-  
!!!!!! ???? ,, -- ---  
~~Strikethrough~~

#### Syntax highlighting  
``` js
var foo = function (bar) {
  return bar++;
};

console.log(foo(5));
``` 

#### Tables  
| Option | Description |
| ------ | ----------- |
| data   | path to data files  |
| engine | engine to be used  |
| ext    | extension to be  |

#### MarkdownChallenge1==============

#### MarkdownChallenge3==============
[Url with spaces](/url with space)  
[Url with no spaces](/url-with-no-space)  

#####No space after markup  
No space **after**, markup  

https://www.url-auto-linking.com  
markpelf@extended-email-autolink.com  
mailto:markpelf@extended-protocol-autolink.com

Color green `#0F0`  
Color green `RGB(0,255,0)`    

#####Punctuation issues  
No punctuation **A**C  
with colon **A:**C  
with dash **A-**C   
with space **A **B   
using undercores __A:__C 

Punctuation issues fixed  
with colon  **A:**&ZeroWidthSpace;C  
with colon  **A:**&#8203;C   
with colon  **A:**&#x200B;C    

#### MarkdownChallenge3============== 

#### MarkdownChallenge2==============
#### Plugins  
`markdown-it` supports `syntax plugins` 

#### Subscript/ Superscript   
- 19^th^
- H~2~O

++Inserted text++  
==Marked text==

#### Footnotes   
Footnote 1 link[^first].  
Duplicated footnote reference[^second].   
[^first]: Footnote **can have markup**  
    and multiple paragraphs.  
[^second]: Footnote text.  

#### Custom containers 
::: warning
*here be dragons*
:::

#### MarkdownChallenge2==============

以下是渲染的变体

上面的图片说明了在不同环境中渲染可能有多么不同和不可预测。

2.3 技巧 – 如何将图片嵌入.md

所以，是的，你可以在Markdown GitHub Readme.md文件中嵌入图片。诀窍在于要正确地做到这一点，以便图片在GitHub网站和Visual Source Code等桌面工具中都能渲染。这里的主要技巧是使用相对文件路径。因此，做到这一点的方法是，在你的仓库中创建一个名为/Readme的目录，该目录将包含要处理的图片文件，并从.md文件使用相对文件路径来访问它。

2.4 技巧 – 注意文本/行末的空格和标点符号

Markdown在文本/行末的空格和标点符号方面有一些奇怪的规则。“Markdown挑战3”清晰地说明了这一点。解释/渲染规则已经随着时间而演变，所以如果你正在处理旧的.md文件，你可能会遇到这样的问题。请小心文本/行末的空格和标点符号。

3 测试方法

我计划从我博客上发布的一些文章中创建一个简单的Readme.md文件，只是一个精简版本。
计划是：

使用真实世界的文本来测试Markdown的编辑/渲染。
嵌入一张较小的图片
嵌入一些代码示例（本例为HTML）
嵌入一些链接
插入一些“Markdown挑战”标记，以测试对语言非标准特性的支持
使用纯Markdown标记，并忽略诸如“将HTML标记嵌入Markdown标记”之类的解决方案来达到某种效果。这虽然可能并且受到Markdown爱好者的喜爱，但我认为有点奇怪。如果我需要将另一种标记语言插入文件，那可能意味着最初选择的标记语言就是错误的，也许所有内容都应该从一开始就用HTML编写。

3.1 测试 Readme.md 文件

这是我将在测试中使用的.md文件。

Custom Bootstrap 5 Breadcrumbs -Ver 2
=====================================

Custom Breadcrumbs for Bootstrap 5 framework

***Abstract: We are presenting code (CSS) for custom Bootstrap 5 breadcrumbs.
This is an improved version of the previously published article.***

1 The need for better Breadcrumbs
---------------------------------

Bootstrap 5 framework is coming with very basic Breadcrumbs implementation. I
needed something much better, both visually and more functional. Over time, in
my applications, I found it very useful to use Breadcrumbs to enable the user to
go back to the higher level, after he drills into details on the particular
item/object. Very important to me was the ability to present **TEXT DATA IN
TWO ROWS**, especially in cases where I am showing some data and ID, like an
indication that is the data for some Account, and at the same time providing the
Account number. I was not satisfied with the solutions I saw on the internet, so
I developed my own. While the title says this is a “Bootstrap 5” library, it is
completely independent of the Bootstrap CSS and only chosen colors were taken
from the Bootstrap CSS to align with the Bootstrap 5 theme. You can use it
independently from Bootstrap if you like. 
### 1.1 Changes in this version
This version incorporates suggestions and code from
Graeme_Grant@codeproject.com to make the code shorter. I do not necessarily
agree with all the suggestions, because I think code human readability is more
important than shorter code. So, I made my own new version. Also, this version
uses Bootstrap Icons [1] instead of Font Awesome Icons.

2 Final result
--------------

Here is what the final result looks like, together with the demo code that
generates it. I created breadcrumbs strips in 3 sizes (large, medium, small),
with optional usage of icons. Colors can be chosen at will, and the hover effect
is present by default, unless explicitly disabled. The hover effect is usually
disabled for the last breadcrumb because that is the current selection in
effect.

![55_pic21](Readme/55_pic21.png)

Here is the HTML code that generates the above rendering. Any web developer
should be able to read the HTML code and match it to the above picture to find
the variant he/she likes. If you want to use icons, you can install the free
version of Bootstrap Icons [1], and refer to it, similar to how it is done in
this example. HTML code for icon usage is a bit complicated because we needed to
separate icons and text into 2 separate elements so they could be styled
independently.

``` js
<!DOCTYPE html>
<html>

<head>
    <link rel="stylesheet" href="breadcrumb3.css" />
    <!-- Download bootstrap icons from https://icons.bootstrap.ac.cn/#install  
        and install -->
    <link rel="stylesheet" href="bootstrap-icons-1.11.3\font\bootstrap-icons.min.css" />
</head>

<body>
    <!--Large size --------------------------------------------------------------->
    <H5>Large size, info case</H5>
    <div class="breadcrumb3-lg ">
        <a href="#" class="breadcrumb3-item info">Accounts</a>
        <a href="#" class="breadcrumb3-item info">Account number</br>123456</a>
        <a href="#" class="breadcrumb3-item primary">Details</a>
    </div>
</body>
</html>
``` 

3 Breadcrumbs CSS
-----------------

Here is the CSS, no JavaScript is needed. I deliberately used the class name
“breadcrumbs3” to avoid name collision with the Bootstrap 5 original class.

See Breadcrumb3.css in the repository. 

4 Full Article
--------------

This is just excerpt from an article published at:
[Custom Bootstrap 5 Breadcrumbs -Ver 2](https://markpelf.com/2114/custom-bootstrap-5-breadcrumbs-ver-2/)

5 References
------------

[1] https://icons.bootstrap.ac.cn/\#install  
[2] [Custom Bootstrap 5 Breadcrumbs -Ver 2](https://markpelf.com/2114/custom-bootstrap-5-breadcrumbs-ver-2/)


#### MarkdownChallenge1==============
__Advertisement :)__  
(c) (C) (r) (R) (tm) (TM) (p) (P) +-  
!!!!!! ???? ,, -- ---  
~~Strikethrough~~

#### Syntax highlighting  
``` js
var foo = function (bar) {
  return bar++;
};

console.log(foo(5));
``` 

#### Tables  
| Option | Description |
| ------ | ----------- |
| data   | path to data files  |
| engine | engine to be used  |
| ext    | extension to be  |

#### MarkdownChallenge1==============

#### MarkdownChallenge3==============
[Url with spaces](/url with space)  
[Url with no spaces](/url-with-no-space)  

#####No space after markup  
No space **after**, markup  

https://www.url-auto-linking.com  
markpelf@extended-email-autolink.com  
mailto:markpelf@extended-protocol-autolink.com

Color green `#0F0`  
Color green `RGB(0,255,0)`    

#####Punctuation issues  
No punctuation **A**C  
with colon **A:**C  
with dash **A-**C   
with space **A **B   
using undercores __A:__C 

Punctuation issues fixed  
with colon  **A:**&ZeroWidthSpace;C  
with colon  **A:**&#8203;C   
with colon  **A:**&#x200B;C    

#### MarkdownChallenge3============== 

#### MarkdownChallenge2==============
#### Plugins  
`markdown-it` supports `syntax plugins` 

#### Subscript/ Superscript   
- 19^th^
- H~2~O

++Inserted text++  
==Marked text==

#### Footnotes   
Footnote 1 link[^first].  
Duplicated footnote reference[^second].   
[^first]: Footnote **can have markup**  
    and multiple paragraphs.  
[^second]: Footnote text.  

#### Custom containers 
::: warning
*here be dragons*
:::

#### MarkdownChallenge2==============