折腾来折腾去

pikipity的blog

Kramdown 语法文档翻译(二)

上接kramdown 语法文档翻译(一)

段落

一个段落的第一行可以加入三个空格的缩进,其他行可以有任意数量的缩进,因为段落支持自动换行。但是需要补充的一点就是,当一个“定义列表行”出现的时候,一个段落会自动中断。

你可以用一个或多个空行来区分两个连续的段落。需要注意的是源文件中的一个空行并不意味着在输出文件中也是一个空行(因为“懒语法”)!如果你希望在输出中有一个空行(就好像 <br/> 标签),你需要在一行结束加上至少两个空格或是两个斜线!注意,一个段落的最后一行不可以是空行,这种空行会被忽略。开头和结尾的空格不会被纳入段落文字中。

下面给出的是一个段落效果的举例(代表空格):

This para line starts at the first column. However,
⋅⋅⋅⋅⋅⋅the following lines can be indented any number of spaces/tabs.
⋅⋅⋅The para continues here.

⋅⋅This is another paragraph, not connected to the above one. But⋅⋅
with a hard line break. \\
And another one.

效果如下:

This para line starts at the first column. However, the following lines can be indented any number of spaces/tabs. The para continues here.

This is another paragraph, not connected to the above one. But
with a hard line break. \ And another one.

标题

krandown支持 “Setex” 和 “atx” 格式的标题。所有形式都可以在一个独立的文件中使用

  • “Setext” 格式

    “Setext” 格式必须以一行文字(标题文字)和一行只有等号(对于第一级标题)或者破折号(对于第二级标题)。标题文字可以在开头加入三个空格,但是开头和结尾的空格都不会被纳入标题文字中。等号和破折号的数量没有区分,一个就足够了,但是多个可能更好看。等号和破折号必须顶头开始。下面是一个例子:

    First level header
    ==================
    
    Second level header
    -----
    
       Other first level header
    =
    

    因为 “Setext” 的标题是在一个块级元素的开始,所以这意味着它们之前必须有空行。但是它们之后不需要有空行:

     This is a normal
     paragraph.
    
     And a Header
     ---------------
     And a paragraph
    
     > This is a blockquote.
    
     And a Header
     ----------------
    

    但是为了文档的易读性最好在 “Setext” 标题的后面也用一个空行。

    值得一提的是一种边缘情况:

     header
     ---
     para
    

    一般来说,"Setext" 标题比“横线规律”(后面将提到)考前

  • “atx” 格式

    “atx” 格式的标题必须以一行以一个或多个井号字符开头然后跟标题文字的文字开始。在井号符号之前不允许有空格。井号的数量代表标题的级数:一个井号代表第一级标题,两个代表第二级标题,以此类推直到最多六个井号代表第六级标题。在标题文字之后你可以加入任意数量的井号。任何标题文字开头和结尾的空格都不会纳入到标题文字中。下面是一个举例:

    # First level hearder
    
    ### Third level header ###
    
    ## Second level header #################
    

    下过如下:

    First level hearder

    Third level header

    Second level header

  • 表明标题 ID

    kranmdown 支持一种非常好的方法来设置标题的 ID,这种方法来自于 PHP Markdown ExtraMaruku:如果你在标题后面跟一个左大括号(和标题文字至少以一个空格隔开)、一个井号、标题 ID 和 一个右大括号,那么就为一个标题设置了一个 ID。如果你在 “atx” 风格的标题后面跟有一个井号,那么标题 ID 必须跟在结尾的井号之后。下面是一个例子:

    Hello    {#id}
    -------
    
    # Hello   {#id}
    
    # Hello   {#id}
    

PS: 此项翻译工程即将变成有生之年系列了。。。



Comments