[website] Support documents' fulltext searching (master) (#3535)
add documents' fulltext search powered by algolia
This commit is contained in:
hffariel
@ -31,9 +31,6 @@ install:
|
||||
before_script:
|
||||
- export PR=https://api.github.com/repos/$TRAVIS_REPO_SLUG/pulls/$TRAVIS_PULL_REQUEST
|
||||
- export BRANCH=$(if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then echo $TRAVIS_BRANCH; else echo `curl -s $PR | jq -r .head.ref`; fi)
|
||||
- echo $BRANCH
|
||||
- sed -i 's/base:.*,/base:\"\/'$BRANCH'\/\",/g' .vuepress/config.js
|
||||
- sed -i 's/docsBranch:.*,/docsBranch:\"'$BRANCH'\",/g' .vuepress/config.js
|
||||
- find ./ -name "*.md" -exec sed -i -e 's/!\[\(.*\)\][(]\(.*\)[)]/<img \:src=\"$withBase\('\''\2'\''\)\" alt=\"\1\">/g' {} \;
|
||||
- rm -rf site-repo
|
||||
|
||||
|
||||
@ -16,6 +16,11 @@
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
// Values would be replaced automatically during the travis' building
|
||||
const BUILDING_BRANCH = process.env.BRANCH || ''
|
||||
const ALGOLIA_API_KEY = process.env.ALGOLIA_API_KEY || ''
|
||||
const ALGOLIA_INDEX_NAME = process.env.ALGOLIA_INDEX_NAME || ''
|
||||
|
||||
function convertSidebar(list, path) {
|
||||
if (list.length > 0) {
|
||||
list.forEach((element, i) => {
|
||||
@ -30,8 +35,18 @@ function convertSidebar(list, path) {
|
||||
return list
|
||||
}
|
||||
|
||||
function buildAlgoliaSearchConfig(lang) {
|
||||
return {
|
||||
apiKey: ALGOLIA_API_KEY,
|
||||
indexName: ALGOLIA_INDEX_NAME,
|
||||
algoliaOptions: {
|
||||
facetFilters: ['lang:' + lang, 'version:' + BUILDING_BRANCH]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
base: '',
|
||||
base: BUILDING_BRANCH.length > 0 ? '/' + BUILDING_BRANCH + '/' : '',
|
||||
locales: {
|
||||
'/en/': {
|
||||
lang: 'en',
|
||||
@ -65,14 +80,15 @@ module.exports = {
|
||||
lastUpdated: 'Last Updated',
|
||||
editLinks: true,
|
||||
docsDir: 'docs',
|
||||
docsBranch: '',
|
||||
docsBranch: BUILDING_BRANCH,
|
||||
searchPlaceholder: 'Search',
|
||||
locales: {
|
||||
'/en/': {
|
||||
algolia: buildAlgoliaSearchConfig('en'),
|
||||
selectText: 'Languages',
|
||||
label: 'English',
|
||||
ariaLabel: 'Languages',
|
||||
editLinkText: 'Edit this page on GitHub',
|
||||
algolia: {},
|
||||
nav: [
|
||||
{
|
||||
text: 'Home', link: '/en/'
|
||||
@ -90,6 +106,7 @@ module.exports = {
|
||||
sidebar: convertSidebar(require('./sidebar/en.js'), '/en/')
|
||||
},
|
||||
'/zh-CN/': {
|
||||
algolia: buildAlgoliaSearchConfig('zh-CN'),
|
||||
selectText: 'Languages',
|
||||
label: '简体中文',
|
||||
editLinkText: '在 GitHub 上编辑此页',
|
||||
@ -107,7 +124,6 @@ module.exports = {
|
||||
text: 'Apache', link: 'https://www.apache.org/', target: '_blank'
|
||||
}
|
||||
],
|
||||
algolia: {},
|
||||
sidebar: {
|
||||
'/zh-CN/': convertSidebar(require('./sidebar/zh-CN.js'), '/zh-CN/')
|
||||
}
|
||||
|
||||
@ -159,6 +159,14 @@ npm ERR! Failed at the docs@ lint script.
|
||||
|
||||
```
|
||||
|
||||
## FullText search
|
||||
|
||||
We use [Algolia DocSearch](https://docsearch.algolia.com/) as our fulltext search engine.
|
||||
|
||||
One thing we need to do is that [Config.json From DocSearch](https://github.com/algolia/docsearch-configs/blob/master/configs/apache_doris.json) 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](https://docsearch.algolia.com/docs/config-file)
|
||||
|
||||
## Deployment
|
||||
|
||||
Just start a PR, and all things will be done automatically.
|
||||
|
||||
247
docs/readme.md
247
docs/readme.md
@ -1,247 +0,0 @@
|
||||
<!--
|
||||
Licensed to the Apache Software Foundation (ASF) under one
|
||||
or more contributor license agreements. See the NOTICE file
|
||||
distributed with this work for additional information
|
||||
regarding copyright ownership. The ASF licenses this file
|
||||
to you under the Apache License, Version 2.0 (the
|
||||
"License"); you may not use this file except in compliance
|
||||
with the License. You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing,
|
||||
software distributed under the License is distributed on an
|
||||
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
KIND, either express or implied. See the License for the
|
||||
specific language governing permissions and limitations
|
||||
under the License.
|
||||
-->
|
||||
|
||||
# Doris Document
|
||||
|
||||
[Vuepress](https://github.com/vuejs/vuepress.git) is used as our document site generator, configurations are in `./docs/.vuepress` folder.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Download and install [nodejs](http://nodejs.cn/download/)
|
||||
|
||||
```bash
|
||||
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' Directories
|
||||
|
||||
```bash
|
||||
.
|
||||
├─ 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.
|
||||
```
|
||||
|
||||
## Start Writing
|
||||
|
||||
1. Write markdown files in multi languages and put them in separated folders `./en/` and `./zh-CN/`. **But they should be with the same name.**
|
||||
|
||||
```bash
|
||||
.
|
||||
├─ en/
|
||||
│ ├─ one.md
|
||||
│ └─ two.md
|
||||
└─ zh-CN/
|
||||
│ ├─ one.md
|
||||
│ └─ two.md
|
||||
```
|
||||
|
||||
2. Frontmatters like below should always be on the top of each file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
{
|
||||
"title": "Backup and Recovery", // sidebar title
|
||||
"language": "en" // writing language
|
||||
}
|
||||
---
|
||||
```
|
||||
|
||||
3. Assets are in `.vuepress/public/`.
|
||||
|
||||
Assuming that there exists a png `.vuepress/public/images/image_x.png`, then it can be used like:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
4. Remember to update the sidebar configurations in `.vuepress/sidebar/` after adding a new file or a folder.
|
||||
|
||||
Assuming that the directories are:
|
||||
|
||||
```bash
|
||||
.
|
||||
├─ en/
|
||||
│ ├─ subfolder
|
||||
│ │ ├─ one.md
|
||||
│ │ └─ two.md
|
||||
│ └─ three.md
|
||||
└─ zh-CN/
|
||||
├─ subfolder
|
||||
│ ├─ one.md
|
||||
│ └─ two.md
|
||||
└─ three.md
|
||||
```
|
||||
|
||||
Then the sidebar configurations would be like:
|
||||
|
||||
```javascript
|
||||
// .vuepress/sidebar/en.js`
|
||||
module.exports = [
|
||||
{
|
||||
title: "subfolder name",
|
||||
directoryPath: "subfolder/",
|
||||
children: ["one", "two"]
|
||||
},
|
||||
"three"
|
||||
]
|
||||
```
|
||||
|
||||
```javascript
|
||||
// .vuepress/sidebar/zh-CN.js
|
||||
module.exports = [
|
||||
{
|
||||
title: "文件夹名称",
|
||||
directoryPath: "subfolder/",
|
||||
children: ["one", "two"]
|
||||
},
|
||||
"three"
|
||||
]
|
||||
```
|
||||
|
||||
5. 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:
|
||||
|
||||
```shell
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
Just start a PR, and all things will be done automatically.
|
||||
|
||||
## What Travis Does
|
||||
|
||||
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:
|
||||
|
||||
1. Prepare nodejs and vuepress enviorment.
|
||||
|
||||
2. Use current branch's name as the relative url path in `.vuepress/config.js`(which is the `base` property).
|
||||
|
||||
3. Build the documents into a website all by vuepress.
|
||||
|
||||
4. Fetch asf-site repo to local directory, and copy `.vupress/dist/` into `{BRANCH}/`.
|
||||
|
||||
5. Push the new site to asf-site repo with `GitHub Token`(which is preset in Travis console as a variable used in .travis.yml).
|
||||
|
||||
## asf-site repository
|
||||
|
||||
Finally the asf-site repository will be like:
|
||||
|
||||
```bash
|
||||
.
|
||||
├─ 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user