Vuepress is used as our document site generator, configurations are in ./docs/.vuepress folder.
Download and install nodejs
npm config set registry https://registry.npm.taobao.org // Only if you are in Mainland China. cd docs && npm install npm run dev
Open your browser and navigate to localhost:8080/en/ or localhost:8080/zh-CN/.
. ├─ docs/ │ ├─ .vuepress │ │ ├─ dist // Built site files. │ │ ├─ public // Assets │ │ ├─ sidebar // Side bar configurations. │ │ │ ├─ en.js │ │ │ └─ zh-CN.js │ ├─ theme // Global styles and customizations. │ └─ config.js // Vuepress configurations. ├─ zh-CN/ │ ├─ xxxx.md │ └─ README.md // Will be rendered as entry page. └─ en/ ├─ one.md └─ README.md // Will be rendered as entry page.
Write markdown files in multi languages and put them in separated folders ./en/ and ./zh-CN/. But they should be with the same name.
. ├─ en/ │ ├─ one.md │ └─ two.md └─ zh-CN/ │ ├─ one.md │ └─ two.md
Frontmatters like below should always be on the top of each file:
--- { "title": "Backup and Recovery", // sidebar title "language": "en" // writing language } ---
Assets are in .vuepress/public/.
Assuming that there exists a png .vuepress/public/images/image_x.png, then it can be used like:
Remember to update the sidebar configurations in .vuepress/sidebar/ after adding a new file or a folder.
Assuming that the directories are:
. ├─ en/ │ ├─ subfolder │ │ ├─ one.md │ │ └─ two.md │ └─ three.md └─ zh-CN/ ├─ subfolder │ ├─ one.md │ └─ two.md └─ three.md
Then the sidebar configurations would be like:
// .vuepress/sidebar/en.js` module.exports = [ { title: "subfolder name", directoryPath: "subfolder/", children: ["one", "two"] }, "three" ]
// .vuepress/sidebar/zh-CN.js module.exports = [ { title: "文件夹名称", directoryPath: "subfolder/", children: ["one", "two"] }, "three" ]
Run npm run lint before starting a PR.
Surely that there will be lots of error logs if the mardown files are not following the rules, and these logs will all be printed in the console:
en/administrator-guide/alter-table/alter-table-bitmap-index.md:92 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: " ```"] en/administrator-guide/alter-table/alter-table-rollup.md:45 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] en/administrator-guide/alter-table/alter-table-rollup.md:77 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] en/administrator-guide/alter-table/alter-table-rollup.md:178 MD046/code-block-style Code block style [Expected: fenced; Actual: indented] en/administrator-guide/alter-table/alter-table-schema-change.md:50 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] en/administrator-guide/alter-table/alter-table-schema-change.md:82 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] en/administrator-guide/alter-table/alter-table-schema-change.md:127 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] en/administrator-guide/alter-table/alter-table-schema-change.md:144 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] en/administrator-guide/alter-table/alter-table-schema-change.md:153 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"] en/administrator-guide/alter-table/alter-table-schema-change.md:199 MD046/code-block-style Code block style [Expected: fenced; Actual: indented] en/administrator-guide/backup-restore.md:45:1 MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1] en/administrator-guide/backup-restore.md:57:1 MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1] en/administrator-guide/backup-restore.md:61:1 MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 3; Style: 1/1/1] npm ERR! code ELIFECYCLE npm ERR! errno 1 npm ERR! docs@ lint: `markdownlint '**/*.md' -f` npm ERR! Exit status 1 npm ERR! npm ERR! Failed at the docs@ lint script.
We use Algolia DocSearch as our fulltext search engine.
One thing we need to do is that Config.json From DocSearch should be updated if a new language or branch is created.
For more detail of the docsearch's configuration, please refer to Configuration of DocSearch
Just start a PR, and all things will be done automatically.
Once a PR accepted, travis ci will be triggered to build and deploy the whole website within its own branch. Here is what .travis.yml does:
Prepare nodejs and vuepress enviorment.
Use current branch's name as the relative url path in .vuepress/config.js(which is the base property).
Build the documents into a website all by vuepress.
Fetch asf-site repo to local directory, and copy .vupress/dist/ into {BRANCH}/.
Push the new site to asf-site repo with GitHub Token(which is preset in Travis console as a variable used in .travis.yml).
Finally the asf-site repository will be like:
. ├─ master/ │ ├─ en/ │ │ ├─ subfolder │ │ │ ├─ one.md │ │ └─ three.md │ └─ zh-CN/ │ ├─ subfolder │ │ ├─ one.md │ └─ three.md ├─ incubating-0.11/ │ ├─ en/ │ │ ├─ subfolder │ │ │ ├─ one.md │ │ └─ three.md │ └─ zh-CN/ │ ├─ subfolder │ │ ├─ one.md │ └─ three.md ├─ index.html // user entry, and auto redirected to master folder └─ versions.json // all versions that can be seleted on the website are defined here
And the versions.json is like:
{ "en": [ { "text": "Versions", // dropdown label "items": [ { "text": "master", // dropdown-item label "link": "/../master/en/installing/compilation.html", // entry page for this version "target": "_blank" }, { "text": "branch-0.11", "link": "/../branch-0.11/en/installing/compilation.html", "target": "_blank" } ] } ], "zh-CN": [ { "text": "版本", "items": [ { "text": "master", "link": "/../master/zh-CN/installing/compilation.html", "target": "_blank" }, { "text": "branch-0.11", "link": "/../branch-0.11/zh-CN/installing/compilation.html", "target": "_blank" } ] } ] }