正文

代码写错报错怎么办Markdown代码块正确用法大全语法符号详解新手避坑指南

/0 浏览量
0905

你是不是也经历过这种崩溃时刻？兴冲冲地写了一行代码，结果粘贴到Markdown文档里，要么显示成乱码，要么格式全乱，要么就是那个该死的报错信息没有被高亮显示。别急，今天咱们就坐下来，像朋友聊天一样，把这个困扰无数新手的问题彻底讲清楚。我见过太多人把Markdown代码块用得生不如死，其实只要搞懂这几个小秘密，你就能从“代码小白”瞬间变身“排版高手”。

代码报错？先别慌，那是它在跟你对话

首先，咱们得聊聊那个让人头疼的“报错”。当你看到红红的一串错误提示时，心里是不是“咯噔”一下？但你知道吗，报错其实是代码在跟你说话，它是在告诉你：“嘿，这里有点不对劲，帮我看看！”

比如，你写了一段Python代码：

name = "张三"
print(Hello, name)

然后控制台蹦出来：

NameError: name 'Hello' is not defined

别急着砸键盘。这个错误在告诉你，“Hello”被当成了变量名，但你没有定义它。正确的写法应该是：

name = "张三"
print("Hello", name)

你看，加上一对引号，问题就解决了。报错并不可怕，可怕的是你看不懂它在说什么。学会解读报错信息，是程序员成长的必经之路。

再比如JavaScript里常见的错误：

let message = "欢迎";
console.log(message + "世界");

如果你写成：

let message = "欢迎";
console.log(message + 世界);

就会报错：ReferenceError: 世界 is not defined。

这时候，你要明白，字符串必须用引号包裹，否则JS会以为你在引用一个变量。

所以，遇到报错，第一步不是到处问人，而是先冷静下来，仔细读报错信息，找出问题所在。绝大多数错误，都能在几十秒内解决。

Markdown代码块：三种写法，你选对了吗？

Markdown的代码块有三种基本写法，新手常常混用，导致效果五花八门。咱们一个一个拆解。

1. 行内代码（Inline Code）

当你想在一段文字中插入一小段代码时，用行内代码。方法很简单，用反引号（`）把代码包起来。

例子：

请用 `pip install requests` 安装请求库。

效果：请用 pip install requests 安装请求库。

注意：反引号是键盘左上角那个键，不是单引号。单引号是文字内容，反引号才是代码标记。

2. 多行代码块（Fenced Code Block）

这是最常用的方式，用三个反引号（”`）包裹多行代码。

例子：

```python
def greet(name):
    return f"你好，{name}！"

print(greet("小明"))


效果：

```python
def greet(name):
    return f"你好，{name}！"

print(greet("小明"))

3. 缩进代码块（Indented Code Block）

这是老式写法，每行代码前面加四个空格或一个Tab。现在用得少了，但有些平台还支持。

例子：

    def greet(name):
        return f"你好，{name}！"

效果：

    def greet(name):
        return f"你好，{name}！"

语法高亮：让代码更美观，也更容易读

你知道吗？在三个反引号后面加上语言名称，就能触发语法高亮。不同的语言，高亮颜色不一样，读起来清晰多了。

常用语言标识符：

  • python 或 py
  • javascript 或 js
  • html
  • css
  • json
  • bash 或 shell
  • sql
  • markdown

例子：

```javascript
const user = { name: "李华", age: 25 };
console.log(user.name);
```

效果：

const user = { name: "李华", age: 25 };
console.log(user.name);

看，const 是蓝色，字符串是绿色，数字是橙色，是不是舒服多了？

新手常见坑：这些错误你踩过吗？

坑一：反引号用成了单引号

这是新手第一大错。单引号（’）和反引号（`）长得像，但功能天差地别。

错误示例：

'print("hello")'

正确写法：

`print("hello")`

坑二：代码块内外反引号数量不一致

如果你代码里本身就有反引号，外层的代码块要用更多反引号包裹。

例子：

```markdown
用三个反引号表示代码块：```
```

这样，内层的三个反引号会被正确识别为代码内容，而不是结束标记。

坑三：忽略空行

在Markdown中，代码块前后最好留空行，否则可能被解析成段落。

错误：

这是代码：
```python
print("hi")

这是结尾。


正确：

```markdown
这是代码：

```python
print("hi")

这是结尾。


### 坑四：语言标识符写错

有些语言没有简写，或者简写不对。

比如：

- `sh` 不是标准标识符，应用 `bash` 或 `shell`
- `vue` 不是标准标识符，应用 `html` 或 `javascript`
- `py3` 不是标准标识符，应用 `python`

## 进阶技巧：代码块的高级用法

### 1. 显示行号

大多数Markdown解析器支持在代码块中显示行号，方便你引用特定行。

例子：

````markdown
```python:example.py {1,3,5}
def hello():
    print("world")

def goodbye():
    print("see you")


效果：

```python:example.py {1,3,5}
def hello():
    print("world")

def goodbye():
    print("see you")
```

注意：不是所有平台都支持行号高亮，GitHub Flavored Markdown 和一些静态站点生成器（如 Hugo、Jekyll）支持，但纯Markdown可能不支持。

### 2. 代码折叠

有些平台支持代码折叠，用`<details>`标签实现。

例子：

```markdown
<details>
<summary>点击展开代码</summary>

```python
print("隐藏的代码")
```

</details>
```

效果：

<details>
<summary>点击展开代码</summary>

```python
print("隐藏的代码")
```

</details>

### 3. 在代码中嵌入Markdown

如果你想在代码块中显示Markdown语法，而不是让它被解析，可以用反引号包裹。

例子：

````markdown
```markdown
# 这是一个标题
**这是加粗**
```

效果：

# 这是一个标题
**这是加粗**

实际案例：手把手教你写一个漂亮的代码示例

假设你要写一个教程，教别人如何用Python打印“Hello, World!”。

错误写法：

首先，打开Python，输入：
print('Hello, World!')
然后运行，就能看到结果。

正确写法：

首先，打开你的Python编辑器，输入以下代码：

```python
print("Hello, World!")

然后按下运行按钮，你将在控制台看到输出：

Hello, World!

是不是清晰多了？代码高亮，结果独立显示，读者一眼就能看懂。


再比如，教别人写一个JavaScript函数：

```markdown
在JavaScript中，你可以这样定义一个函数：

```javascript
function add(a, b) {
    return a + b;
}

console.log(add(3, 5)); // 输出 8

注意，return 语句用于返回计算结果，而 console.log 用于在控制台输出。 “`

不同平台的细微差别

不同的Markdown平台，对代码块的支持略有不同。

GitHub

  • 支持所有常用语言高亮
  • 支持行号（通过插件或第三方服务）
  • 不支持代码折叠

CSDN

  • 支持语言高亮
  • 支持行号（在编辑器中勾选）
  • 不支持代码折叠

知乎

  • 支持语言高亮
  • 不支持行号
  • 不支持代码折叠

语雀/Notion

  • 支持语言高亮
  • 支持代码折叠
  • 部分支持行号

所以，当你换平台时，如果发现效果不一样，别慌，那是平台特性不同，不是你的Markdown写错了。

最后，记住这三条黄金法则

  1. 用反引号，别用单引号：这是最基本的，弄错了全盘皆输。
  2. 注明语言，高亮更清晰：哪怕只是写个python或js，也能让代码读起来舒服十倍。
  3. 前后留空行，格式更稳定：别让Markdown解析器猜你的意图，明确一点，少出 bug。

好了，今天的内容就到这里。希望这篇指南能帮你摆脱Markdown代码块的困扰。记住，编程和写作一样，细节决定成败。下次再遇到报错，别慌，先看看是不是代码块写错了。如果你还有其他问题，欢迎随时问我，咱们一起进步！

-- 展开阅读全文 --