.i18n/conf.yml

i18n.site的配置文件是.i18n/conf.yml，內容如下:

i18n:
  fromTo:
    en:
upload:
  ext:
    - md
nav:
  - i18n: home
    use: Toc
    url: /
  - i18n: doc
    menu: NB demo1,demo2
    use: Doc
  - i18n: blog
    use: Blog
addon:
  - i18n.addon/toc

其中，upload的ext:配置項，表示发布時只上傳.md。

頂部導航 nav

nav:的配置選項，對應首頁頂部的導航菜單。

其中，i18n: home對應着en/i18n.yml中home: Home(這里en是項目翻譯的源語言)。

en/i18n.yml內容是導航菜單中顯示的文本，會根據配置中的fromTo翻譯，比如翻譯到zh/i18n.yml。

翻譯完成后，可以修改譯文的yml的值，但不要增刪譯文yml的鍵。

`use: Toc` 有大綱的單文件模板

nav配置中:

  - i18n: home
    use: Toc
    url: /

use: Toc表示使用Toc模板渲染，這是渲染單個Markdown模板。

TOC是Table of Contents的縮寫，此模板渲染時會在側欄顯示此Markdown文件的大綱。

url:表示Markdown的文件路徑（/對應的是根目錄/README.md，此文件名需前綴大寫、后綴小寫）。

`use: Md` 無大綱的單文件模板

Md模板和Toc模板相同，都用于渲染單個Markdown文件。但是Md模板不會在側欄顯示大綱。

你可以修改上面配置中的use: Toc為use: Md，再次在md目錄下運行i18n.site，然后訪問開发預覽的網址，观察首頁的變化。

`use: Blog` 博客模板

博客模板會按发布時間的順序顯示文章列表(標題和摘要)。

→ 點此了解具體配置

`use: Doc` 多文件文檔模板

配置文件中:

  - i18n: doc
    menu: NB demo1,demo2
    use: Doc

表示使用Doc進行模板渲染。

Doc模板支持集成多個MarkDown來生成單個或多個項目的文檔大綱。

多項目多文件

.i18n/conf.yml中i18n:doc的配置是多項目多文件渲染模式。

這里，menu: NB demo1,demo2，表示用NB模板渲染下拉菜單。

NB,是Name Breif的縮寫，表示下拉菜單可以顯示項目的名稱和標語。

NB后面是傳給它的參數demo1,demo2。

注意: ** demo1,demo2中的逗號,前后不要有空格**。

以上參數，對應的目錄索引文件是:

en/demo1/TOC
en/demo2/TOC

單項目多文件

如果你只有一個項目，那么可以配置如下。

  - i18n: doc
    url: flashduty
    use: Doc

[!WARN] 單項目多文件不支持配置 url 為根路徑 / 如果__conf.yml → nav:__沒有配置根路徑，訪問網站首頁時，會自動重寫到nav:配置下的第一個網址。這樣設計是為了通過目錄，更好地區分項目文檔、博客等內容。建議用單文件單頁面作為首頁。

[!TIP] 若不寫url，url默認為i18n的值，此規則對于其他模板同樣生效。

TOC 目錄索引

如果配置中啟用use: Doc模板，就請在.i18n/conf.yml中啟用插件i18n.addon/toc，配置如下:

addon:
  - i18n.addon/toc

i18n.site會自動安裝執行此插件，讀取TOC目錄索引文件，來生成目錄大綱的json。

如果是單項目多文件，TOC根目錄是源語言目錄下url:對應的目錄，比如源語言是中文：url: flashduty對應的文件是zh/flashduty/TOC。

如果是多項目多文件，不需要配置url:，TOC根目錄是i18n的值對應的目錄，

內容詳解

en/blog/TOC內容如下:

README.md

news/README.md
  news/begin.md

用縮進表示層級

上面en/blog/TOC第一行的README.md對應的是下圖中的i18n.site，也就是項目名稱。

后續的兩行，如下面截圖所示。

news/README.md對應的是News， news/begin.md對應的是Our Product is Online !

TOC文件通過縮進，表示大綱層級關系，支持多層縮進, 以# 開頭的行為注釋。

父層級只寫標題，不寫內容

有多層縮進的情況下，父層級只寫標題，不寫內容。否則會導致排版錯亂。

項目 README.md

項目的README.md，比如en/demo2/README.md中可以寫內容。

注意，此文件的內容不顯示目錄大綱，所以建議控制篇幅，寫一些簡短的介紹即可。

項目標語

可以看到，Deme Two在下拉菜單和目錄大綱項目名的下方，有它的項目標語:Your Project slogan。

這對應的是en/demo2/README.md第一行:

# Demo Two : Your Project slogan

項目README.md一級標題首個冒號:后面的內容，會被視為項目標語。

中日韓用戶請注意，要用半角冒號:而不是全角冒號。

如何批量移動 TOC ？

TOC文件需要放在源語言的目錄下。

比如，源語言是中文，那么上面TOC就是zh/blog/TOC。

如果修改了源語言，就需要批量移動項目中的某語種的TOC文件到另一語種。

可以參考如下命令：

rsync -av --remove-source-files --include='*/' \
--include='TOC' --exclude='*' en/ zh/

請修改上面命令中的en/和zh/為您的語種代碼。

無配置路徑的默認加載

訪問的某個路徑，如果路徑前綴沒有在nav:中配置，則默認加載路徑對應的MarkDown文件，并用Md模板渲染。

比如，訪問/test，同時nav:配置未此路徑的前綴，当前瀏覽語言是英文（代碼en），則默認會加載/en/test.md，并使用Md模板渲染。

如果/en/test.md此文件不存在，則會顯示默認的404頁面。