.i18n/conf.yml
The configuration file for i18n.site
is .i18n/conf.yml
, and the content is as follows:
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
Among them, the ext:
configuration item under upload
indicates that only .md
files will be uploaded when publishing.
Top Navigation nav
The nav:
configuration options correspond to the navigation menu at the top of the homepage.
Among them, i18n: home
corresponds to home: Home
in en/i18n.yml
(where en
is the source language of the project translation).
The content of en/i18n.yml
is the text displayed in the navigation menu, which will be translated according to the fromTo
configuration, for example, translated to zh/i18n.yml
.
After the translation is completed, you can modify the values in the translated yml
file, but do not add or delete keys in the translated yml
file.
use: Toc
- Single File Template with Table of Contents
In the nav
configuration:
- i18n: home
use: Toc
url: /
use: Toc
indicates that the Toc
template is used for rendering, which is for rendering a single Markdown
file.
TOC
is the abbreviation of Table of Contents
. When this template is rendered, the outline of this Markdown
file will be displayed in the sidebar.
url:
represents the file path of the Markdown
file ( /
corresponds to the root directory /README.md
, and this file name requires an uppercase prefix and a lowercase suffix).
use: Md
- Single File Template without Table of Contents
The Md
template is similar to the Toc
template and is used to render a single Markdown
file. However, the Md
template does not display the outline in the sidebar.
You can change use: Toc
to use: Md
in the above configuration, run i18n.site
in the md
directory again, and then visit the development preview URL to observe the changes on the homepage.
use: Blog
- Blog Template
The blog template displays a list of articles (titles and abstracts) in the order of their publication dates.
→ Click here to learn about the specific configuration
use: Doc
- Multi-File Document Template
In the configuration file:
- i18n: doc
menu: NB demo1,demo2
use: Doc
It indicates that the Doc
template is used for rendering.
The Doc
template supports integrating multiple Markdown
files to generate a document outline for single or multiple projects.
Multiple Projects and Multiple Files
The i18n:doc
configuration in .i18n/conf.yml
is for multi-project multi-file rendering mode.
Here, menu: NB demo1,demo2
indicates that the NB
template is used to render the drop-down menu.
NB
is the abbreviation of Name Brief
, indicating that the drop-down menu can display the project's name and slogan.
NB
is followed by the parameters demo1,demo2
passed to it.
Note: There should be no spaces before and after the comma ,
in demo1,demo2
.
The corresponding directory index file for the above parameters is:
Single Project and Multiple Files
If you have only one project, you can configure it as follows.
- i18n: doc
url: flashduty
use: Doc
[!WARN]
Single project with multiple files does not support configuring url
as the root path /
If the root path is not configured in conf.yml → nav:, when accessing the homepage of the website, it will automatically redirect to the first URL under the nav:
configuration.
This design is to better distinguish project documents, blogs, and other content through directories.
It is recommended to use a single file and a single page as the homepage.
[!TIP]
If url
is not specified, url
defaults to the value of i18n
. This rule also applies to other templates.
TOC Table of Contents Index
If the use: Doc
template is enabled in the configuration, please enable the plugin i18n.addon/toc
in .i18n/conf.yml
. The configuration is as follows:
addon:
- i18n.addon/toc
i18n.site
will automatically install and execute this plugin, read the TOC
directory index file, and generate the directory outline in json
format.
If it is a single project with multiple files, the root directory of TOC
is the directory corresponding to url:
in the source language directory. For example, if the source language is Chinese, the file corresponding to url: flashduty
is zh/flashduty/TOC
.
If it is multiple projects and multiple files, there is no need to configure url:
. The root directory of TOC
is the directory corresponding to the value of i18n
Detailed Content Explanation
The content of en/blog/TOC
is as follows:
README.md
news/README.md
news/begin.md
Indentation is used to indicate levels
The first line of en/blog/TOC
above, README.md
, corresponds to i18n.site
in the image below, which is the project name.
The next two lines are as shown in the screenshot below.
news/README.md
corresponds to News
news/begin.md
corresponds to Our Product is Online!
The TOC
file uses indentation to indicate the hierarchical relationship of the outline, supports multi-level indentation, and lines starting with #
are comments.
The parent level only writes the title, not the content
When there are multiple levels of indentation, the parent level only writes the title and not the content. Otherwise, the layout will be messed up.
Project README.md
The README.md
file of the project, such as en/demo2/README.md
, can contain content.
Note that the content of this file does not display a table of contents outline, so it is recommended to keep it short and write a brief introduction.
Project Slogan
You can see that Demo Two
has its project slogan below the drop-down menu and the catalog outline project name: Your Project slogan
.
This corresponds to the first line of en/demo2/README.md
:
# Demo Two : Your Project slogan
The content after the first colon :
of the first-level heading in the project README.md
is considered the project slogan.
Users from China, Japan, and Korea, please note that you should use a half-width colon :
instead of a full-width colon.
How to Move TOC in Bulk?
TOC
files need to be placed in the directory of the source language.
For example, if the source language is Chinese, then the TOC
above is zh/blog/TOC
.
If the source language is modified, you need to batch move the TOC
files of a certain language in the project to another language.
You can refer to the following command:
rsync -av --remove-source-files --include='*/' \
--include='TOC' --exclude='*' en/ zh/
Please modify en/
and zh/
in the above command to your language code.
Default Loading Without Configuration Path
For a certain path being accessed, if the path prefix is not configured in nav:
, the Markdown
file corresponding to the path will be loaded by default and rendered using the Md
template.
For example, if /test
is accessed and nav:
is not configured for this path, and the current browsing language is English (code en
), then /en/test.md
will be loaded by default and rendered using the Md
template.
If /en/test.md
does not exist, the default 404
page will be displayed.