Markdown 檔案中的 HTML

Markdown 是一種書寫格式HTML 是一種發布格式,因此,Markdown 語法的目的並非提供所有 HTML 的靈活性,只是最常見的文字元素。如果需要進行較複雜的操作,您可以在 Markdown 檔案中使用任何 DevSite 支援的內嵌 HTML 代碼和區塊層級代碼。不必表明你要從 Markdown 改用 HTML,只要按照下方範例使用 HTML 標記即可。

This sentence is in Markdown with a <b>bold inline HTML tag</b>.

內嵌 HTML

內嵌 HTML 代碼可以在 Markdown 段落、清單項目或標題中使用,也可以包含 Markdown 語法 (例如**strong***emphasis* 等)如果您想將注意力吸引到一小段程式碼,這個方式就很實用,如以下範例所示。

This is a Markdown paragraph about Java:
<code>System.out.format("The square of *%d* is *%f*.*%n*", i, r);</code>

區塊層級 HTML

DevSite 支援的區塊層級 HTML 標記,必須與周圍內容以空白行分隔。此外,有別於內嵌 HTML 代碼,Markdown 語法 (例如系統不會轉譯區塊層級 HTML 標記中的 **strong***emphasis* 等),如以下範例所示。

This is a Markdown paragraph that explains Java format strings:
                                  // required blank line
<pre>
  System.out.format("The square of *%d* is *%f*.*%n*", i, r);
</pre>
                                  // required blank line
This is another Markdown paragraph.

最佳做法

我們建議採用下列方式,在 Markdown 檔案中設定 HTML 格式,以免 DevSite 發生轉譯錯誤。

請勿使用不支援的區塊層級 HTML 標記 DevSite 支援許多區塊層級的 HTML 標記。但加入不支援的程式碼會將 HTML 轉譯為文字或破壞程式碼。

縮排時不應加入額外的定位點或空格 區塊層級的起始和結束標記不得使用 Tab 或空格縮排。部分編輯器會自動新增額外的分頁或空格,請小心!

This is a regular paragraph in Markdown.

<p>
    This is an HTML paragraph with proper indentation!
</p>

This is a regular paragraph in Markdown.

請注意,取消縮排的程式碼是相對的概念

舉例來說,在 Markdown 中建立清單時,你不必將區塊層級的開始與結束標記縮排。

* This is a list item in Markdown

<p>This is an HTML paragraph with proper indentation!</p>

* This is a list item in Markdown

請勿在開始與結束標記之間加入空白行

轉換在 Markdown 和 HTML 之間十分容易,但只要加上空白行的空白行,系統就有可能無法正確顯示網頁。

This is a regular paragraph in Markdown.

<section>
  <p>
    hello
   </p>
  <p>
    hello
  </p>
</section>

This is a regular paragraph in Markdown.