SRS-DOCS
The documents for ossrs.net or ossrs.io.
Usage
Please install node, npm and yarn:
brew install node
npm install -g --force npm yarn
Install dependencies:
yarn install
Start local development server:
yarn start
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
Language
Build English and Chinese versions:
yarn build
yarn serve
Note: Please see
package.json
for detail command.
Change baseUrl
$ yarn cross-env BASE_URL='/custom-base-url/' docusaurus build
This command uses '/custom-base-url/'
instead of the default baseUrl('/lts/'
) to generate static content.
Dockers
- Docker hub: ossrs/docs
- Aliyun ACR: registry.cn-hangzhou.aliyuncs.com/ossrs/docs
Translate
Start en-us site
Start your localized site in dev mode, using the locale of your choice:
$ yarn run start -- --locale en-us
Your site is accessible at http://localhost:3000/en-us/
.
Translate site content
Step 1: Translate JSON files
Run the write-translations command:
$ yarn docusaurus write-translations -- --locale en-us
It will extract and initialize the JSON translation files that you need to translate.
The JSON files will be in generated in /i18n/en-us/
path.
Step2: Translation Markdown files
First, you should copy markdown files in "/docs" and "/blog" folder to "/i18n/en/docusaurus-plugin-content-docs/current" and "/i18n/en/docusaurus-plugin-content-blog/current", then translation markdown files.
Environment variable
Name | Default value | Level | Effect |
---|---|---|---|
URL | "https://ossrs.io" |
high | site url |
BASE_URL | "/" |
high | site baseUrl |
DEFAULT_LOCALE | "en-us" |
high | site default locale |
REGION | "" |
low | use site default config template, config in template can be overwritten by high levle environment variable |
REGION Environment variable
''
NONE: yarn build
Use configs in '/config/default.js'
.
{
url: 'https://ossrs.io',
baseUrl: '/',
defaultLocale: 'en-us',
plugins: [
[
'./config/docusaurus-dynamic-copyright-plugin',
{
copyright: `<p>©2013~${new Date().getFullYear()} SRS</p>`,
},
],
],
}
"zh-cn"
yarn cross-env REGION='zh-cn' docusaurus build
Use configs in '/config/zh-cn.js'
.
{
url: 'https://ossrs.net',
baseUrl: '/lts/',
defaultLocale: 'zh-cn',
plugins: [
[
'./config/docusaurus-dynamic-copyright-plugin',
{
copyright: `<p>©2013~${new Date().getFullYear()} SRS <a href="https://beian.miit.gov.cn">京ICP备19056366号-1</a></p>`,
},
],
],
};
search
our documentation site using Typesense DocSearch. for more details, please refer:using-typesense-docsearch and Search for Documentation Sites
how to enable search on local environment?
- start typesense, it's an open-source instant-search engine, that supplies http api service to query items. we choose to Self-Host our own server with:
yarn typesense
- build and serve the documentation site:
yarn build
yarn serve
- start scraper, which scrapes the site content and indexes the data in the Typesense server:
yarn scraper
when scraper finished,you can do search in the html.
how to add a new document
add a new document to an existing directory
for example, add a new document (example.md) in tutorial
- add document in i18n/en-us/
cd i18n/en-us/docusaurus-plugin-content-docs/current/tutorial/ && touch example.md
- add document in i18n/zh-cn/
cd i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/ && touch example.md
- sidebar config, please refer:https://docusaurus.io/zh-CN/docs/next/sidebar/items
Add ['tutorial/example'] to the tutorialSidebar configuration item in sidebar.json, please note that not with the .md suffix
Once the configuration is complete, you can see the new documentation in the tutorial directory
add a new directory and documentation
for example, add a new document (mydir/new-example.md) in tutorial
- add document in i18n/en-us/
cd i18n/en-us/docusaurus-plugin-content-docs/current/tutorial/ && mkdir -p mydir && touch new-example.md
- add document in i18n/zh-cn/
cd i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/ && mkdir -p mydir && touch new-example.md
- sidebar config, please refer:https://docusaurus.io/zh-CN/docs/next/sidebar/items
add a category sidebar config in tutorialSidebar of sidebar.json, and config items of the subfile
{
type: 'category',
label: 'NewDir',
link: {
type: 'generated-index',
},
collapsed: true,
items: ['tutorial/mydir/new-example'],
}
Once the configuration is complete, you can see the new documentation in the tutorial directory
- modify the chinese name of new category
run: yarn docusaurus write-translations -- --locale zh-cn
when finish, modify the i18n/zh-cn/docusaurus-plugin-content-docs/current.json file's 'NewDir' to your expected chinese name.
Versioning
- First, make sure the current docs version (the ./i18n/en-us/docusaurus-plugin-content-docs/current directory) is ready to be frozen.
- Enter a new version number.
yarn run docusaurus docs:version 4.2.0
- change the current version label in
docusaurus.config.js
file
docs: {
path: 'i18n/en-us/docusaurus-plugin-content-docs/current',
sidebarPath: require.resolve('./sidebars.js'),
// Please change this to your repo.
editUrl: ({ versionDocsDirPath, docPath, locale, version }) => {
return 'en-us' == locale
? `https://github.com/ossrs/srs-docs/edit/main/${versionDocsDirPath}/${docPath}`
: `https://github.com/ossrs/srs-docs/edit/main/i18n/${locale}/docusaurus-plugin-content-docs/${version}/${docPath}`;
},
// lastVersion: 'current',
lastVersion: versions[0],
versions: {
current: {
+ label: `4.3.0 🚧`,
- label: `4.2.0 🚧`,
},
},
remarkPlugins: [require('mdx-mermaid')],
},