本文提供了如何在 Discourse 中使用 Markdown, BBCode, 和 HTML 来发布格式化文本。
需要的用户级别:所有用户都可以使用
官方原文链接:Posting code or preformatted text - Using Discourse - Discourse Meta
当有代码希望在 Discourse 中进行分享的时候,或者针对一些错误日志需要发布在 Discourse 上的时候。如果我们不对代码进行格式化,对于这些内容读起来是非常费劲的,同时在很多代码中会包含有空格和一些其他的字符,那么在内容转换的时候,这些内容就会脱离其本意了。
概要
在本指南中,你可以学到:
- 如何格式化行内代码。
- 如何格式化单行代码。
- 如何格式化多行代码。
- 如何为代码格式化使用 BBCode 和 HTML。
- 如何禁用代码自动格式化。
行内代码格式化
要对行内的代码或者特殊文字进行格式化,在需要进行格式化的内容前后部分使用单引号。
这个可以是在一个文本中,或者代码在另外一行 。
行内代码格式化不会为要格式化的代码应用任何格式(请查看下面的示例),只会对要格式化的代码使用代码样式(“code style”)。
示例 1:
输入:
`This is a line of code`
输出:
This is a line of code
示例 2:
输入:
Here’s some text with `a bit of code` inside!
输出:
Here’s some text with a bit of code
inside!
单行代码格式化
如果需要对当行的代码进行格式化,那么只需要在当行的代码前面添加 4 个空格就行。
单行中的所有内容都会被格式化成代码,直到下一行的开始。
示例:
输入:
All text after 4 spaces will be formatted.
输出:
All text after 4 spaces will be formatted.
多行代码格式化
针对多行代码,如果还使用单行代码进行格式化的话,那么整个过程就会显得非常麻烦。
尤其是很多代码还会使用空格进行缩进。
使用单行空格代码格式化将会影响整个代码块的缩进。
这个时候可以使用 3 个单引号(backticks (```))作为代码的开头,这 3 个单引号需要独立成行。
同时,这个 3 个单引号之前不能有空格,如果有空格的话,整个代码块可能无法格式化。
示例:
输入:
``` public class CodeFormatting { public static void main(String[] args) { System.out.println("I can format code now!"); } } ```
输出:
public class CodeFormatting {
public static void main(String[] args) {
System.out.println("I can format code now!");
}
}
BBCode 和 HTML
除了 Markdown 格式化外,Discourse 还能够支持 BBCode 和 HTML。
针对 HTML 使用 <pre>
和 <code>
标签:
<pre><code>
public class CodeFormatting {
public static void main(String[] args) {
System.out.println("I can format code now!");
}
}
</code></pre>
针对 BBCode,使用 [code]
标签:
[code]
public class CodeFormatting {
public static void main(String[] args) {
System.out.println("I can format code now!");
}
[/code]
针对特定的程序语言
在默认情下,Discourse 会针对你的输入格式来自动侦测使用的语言。
当然你也可以手动针对代码块指定语言,在 3 个单引号后面输入你希望格式化的语言即可。
``` your_language
# Your code here
示例:
针对 Ruby 语言:
输入:
``` ruby 3.times do |stuff| stuff.do end ```
输出:
3.times do |stuff|
stuff.do
end
能够支持的语言必须是下面能够支持语法高亮的语言 highlighted languages`。
能够支持的语言列表可以在 on GitHub 页面中访问到。
当然,你可以可以使用 default code lang
配置来配置默认的语言。
不使用语法高亮
如果你不希望输入的文本或者代码块使用任何语法高亮,那么在语言选择部分使用 text
来代替。
示例:
输入:
``` text
Your text to NOT highlight here
输出:
Your text to NOT highlight here
最佳实践
- 针对行内代码,总是使用单引号来包裹你需要格式化的文本。
- 如果要分享多行代码,把代码进行格式化。
- 针对文本和日志,避免使用自动代码样式,因为这些文本多是纯文本,之间使用文本格式就好了。
- 当发现自动样式识别没有对代码进行正确识别的时候,记得为你的代码指定正确的语言。