.i18n/conf.yml
The configuration file for i18n.site
is .i18n/conf.yml
.
Except for the settings of i18
, ignore:
and i18n:
, the configuration file is as follows:
upload:
ext:
- md
nav:
- i18n: home
use: Toc
url: /
- i18n: doc
menu: NB demo1,demo2
use: Doc
- i18n: blog
use: Doc
Among them, the upload
's ext:
configuration item indicates that only .md
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
.
en/i18n.yml
will be translated into multiple languages, such as zh/i18n.yml
.
After the translation is completed, you can modify the value of the translated yml
, but do not add or delete the key of the translated yml
.
use: Toc
, Single File Template (With Outline)
In nav
:
- i18n: home
use: Toc
url: /
use: Toc
means using the Toc
template for rendering, which is for rendering a single Markdown
template.
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 Markdown
(/
corresponds to the root directory /README.md
, and this file name requires an uppercase prefix and a lowercase suffix).
use: Md
, Single File Template (No Outline)
The Md
template is the same as the Toc
template and is both used to render a single Markdown
file. But the Md
template does not show the outline in the sidebar.
You can modify use: Toc
in the above configuration to use: Md
, run i18n.site
again in the md
directory, and then visit the development preview URL to observe the changes on the homepage.
Default Loading Without Configuration Path
If a certain path is accessed and its 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 page language is English (code en
), /en/test.md
will be loaded by default and rendered using the template Md
.
If /en/test.md
this file does not exist, the default 404
page will be displayed.
use: Doc
, Multi-File Template
In the configuration file:
- i18n: blog
use: Doc
Indicates using Doc
for template rendering.
Doc
template supports integrating multiple MarkDown
to generate document outlines for single or multiple projects.
Single Project (Multiple Files)
The blog
mentioned above is the single-item mode of Doc
.
- i18n: blog
url: blog
use: Doc
When the URL is empty, it defaults to the value specified in i18n
If url
is not written, url
defaults to the value of i18n
. This rule also applies to other templates.
The above writing is equivalent to url: blog
, and its corresponding file is en/blog/TOC
.
Multiple Projects
The configuration of i18n:doc
in .i18n/conf.yml
is in the multi-project mode.
- i18n: doc
menu: NB demo1,demo2
use: Doc
Here, menu: NB demo1,demo2
, means using the NB
template to render the drop-down menu.
NB
, which is the abbreviation of Name Breif
, means that the drop-down menu can display the name and slogan of the project.
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:
TOC Table of Contents Index
i18n.site
will execute the js
plugin .i18n/hook/after.tran/TOC.js
in the demo warehouse to read the doc
template configuration corresponding to the TOC
directory index file to generate the json
directory outline.
If you use the doc
template, you must have this plugin.
If you initialize the i18n.site
project from an empty folder, remember to copy the .i18n
of the demo project to your directory.
The Doc
template will render the table of contents outline based on the generated json
.
Detailed Content Explanation
The content of en/blog/TOC
is as follows:
README.md
news/README.md
news/begin.md
Use indentation to indicate levels
The first line of en/blog/TOC
above, README.md
, corresponds to i18n.site
in the figure 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
files, through indentation, represent the hierarchical relationship of the outline, support multi-level indentation, and the lines starting with #
are comments.
At the parent level, only the title should be written, without including the content
In cases of multiple indentation levels, the parent level should also only contain the title, omitting the content to avoid typography issues.
Project README.md
Content may be included within the README.md
of the project, for instance, in en/demo2/README.md
.
Note that the content of this file does not display a table of contents outline, so it is advisable to control the length and just write a brief introduction.
Project Slogan
It can be seen that Deme Two
has its project slogan below the drop-down menu and the project name in the catalog outline: 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 title of the project README.md
will be regarded as the project slogan.
Users from China, Japan, and Korea, please note that a half-width colon :
should be used instead of a full-width colon.
How to batch move the TOC?
The TOC
file needs to be placed in the directory of the source language.
For example, if the source language is Chinese, then the above TOC
is zh/blog/TOC
.
If the source language is modified, it is necessary to batch move the TOC
files of a certain language in the project to another language.
You can refer to the following commands:
rsync -av --remove-source-files --include='*/' \
--include='TOC' --exclude='*' en/ zh/
Please modify en/
and zh/
in the above command to your language code.