The documents for SRS

For development, you will only need Node.js and a node global package, Yarn, installed in your environement.

• Node installation on Windows

  Just go on official Node.js website and download the installer. Also, be sure to have git available in your PATH, npm might need it (You can find git here).

• Node installation on Ubuntu

  You can install nodejs and npm easily with apt install, just run the following commands.

  $ sudo apt install nodejs
  $ sudo apt install npm
  

• Other Operating Systems

  You can find more information about the installation on the official Node.js website and the official NPM website.

If the installation was successful, you should be able to run the following command.

$ node --version
v14.18.1

$ npm --version
6.14.15

If you need to update npm, you can make it using npm! Cool right? After running the following command, just open again the command line and be happy.

$ npm install npm -g

After installing node, this project will need yarn too, so just run the following command.

  $ npm install -g yarn

If the installation was successful, you should be able to run the following command.

$ yarn --version
1.22.15

The search function relies on two docker images, typesense and scraper, so you need to install docker in your local development environment. the installation can refer:docker install

$ yarn install

$ 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.

$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

$ 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.

• Docker hub: ossrs/docs
• Aliyun ACR: registry.cn-hangzhou.aliyuncs.com/ossrs/docs

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/.

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.

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.

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>`,
      },
    ],
  ],
}

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>`,
      },
    ],
  ],
};

our documentation site using Typesense DocSearch. for more details, please refer:using-typesense-docsearch and Search for Documentation Sites

1. 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

2. build and serve the documentation site:

  yarn build
  yarn serve

3. 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.

for example, add a new document (example.md) in tutorial

1. add document in i18n/en-us/

cd i18n/en-us/docusaurus-plugin-content-docs/current/tutorial/ && touch example.md

2. add document in i18n/zh-cn/

cd i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/ && touch example.md

3. 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

for example, add a new document (mydir/new-example.md) in tutorial

1. add document in i18n/en-us/

cd i18n/en-us/docusaurus-plugin-content-docs/current/tutorial/ && mkdir -p mydir && touch new-example.md

1. add document in i18n/zh-cn/

cd i18n/zh-cn/docusaurus-plugin-content-docs/current/tutorial/ && mkdir -p mydir && touch new-example.md

3. 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

4. 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.

See versioning guide here.

1. First, make sure the current docs version (the ./i18n/en-us/docusaurus-plugin-content-docs/current directory) is ready to be frozen.
2. Enter a new version number.

yarn run docusaurus docs:version 4.2.0

3. 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')],
        },