OpenList Docs

What is OpenList Docs ​

OpenList Docs 是什么 ​

OpenListTeam/OpenList-Docs ​

OpenListTeam/OpenList-Docs is the official documentation website for OpenList, led by @cxw620 and collaboratively developed with other main contributors. Built with Valaxy framework, it provides comprehensive documentation for OpenList, including installation guides, configuration instructions, API references, and ecosystem information. The documentation supports multiple languages and features real-time builds from the GitHub repository.

OpenListTeam/OpenList-Docs 是 OpenList 的官方文档网站，由 @cxw620 牵头，和其他主要贡献者共同协作完成。基于 Valaxy 框架构建，为 OpenList 提供全面的文档，包括安装指南、配置说明、API 参考和生态系统信息。文档支持多种语言，并基于 GitHub 仓库实时构建。

How to use OpenList Docs ​

如何使用 OpenList Docs ​

You can directly access doc.oplist.org.cn to view the documentation.

可直接在线访问doc.oplist.org.cn 查阅文档。

Local Development ​

Prerequisites ​

  • Node.js: Required for running the development environment
  • pnpm: Recommended package manager
  • Git: For version control and cloning the repository

  1. Clone the repository

    bash
    git clone https://github.com/OpenListTeam/OpenList-Docs.git
cd OpenList-Docs

  2. Install dependencies

    bash
    pnpm install

  3. Start development server

    bash
    pnpm dev

  4. Open in browser

    The documentation site will be available at http://localhost:4859

Building ​

In Windows, you may need to run npm install -g win-node-env to solve the NODE_OPTIONS environment variable problem.

bash
# Build static site
pnpm build

# Preview build
pnpm serve

本地开发 ​

环境要求 ​

  • Node.js：运行开发环境所需
  • pnpm：推荐的包管理器
  • Git：用于版本控制和克隆仓库

  1. 克隆仓库

    bash
    git clone https://github.com/OpenListTeam/OpenList-Docs.git
cd OpenList-Docs

  2. 安装依赖

    bash
    pnpm install

  3. 启动开发服务器

    bash
    pnpm dev

  4. 在浏览器中打开

    文档站点将在 http://localhost:4859 处可用

构建 ​

在Windows操作系统下，可能需要运行npm install -g win-node-env解决NODE_OPTIONS环境变量问题。

bash
# 构建静态站点
pnpm build

# 预览构建
pnpm serve

Development Tips ​

:::tip Markdown Parsing Issues When writing documentation, please note these important parsing rules:

  1. Language Block Syntax: For language-specific content blocks, only use one closing ::: at the end:

    Wrong Content Syntax - LightWrong Content Syntax - Dark

    The above should be written as:

    Correct Content Syntax - LightCorrect Content Syntax - Dark

    The language will automatically switch when encountering :::en.

  2. Title Language Specification: Titles must use { lang="en" } syntax and cannot use language blocks:

    Correct Title Syntax - LightCorrect Title Syntax - Dark

    Do NOT use:

    Wrong Title Syntax - LightWrong Title Syntax - Dark

  3. Text Format Convention: For better readability in plain text environments, please follow the English first, then Chinese order when writing bilingual content. This makes it easier to observe and navigate the documentation structure in text editors and version control systems.

  4. Line Break Before Closing :::: Always add a line break before the closing :::, especially when using lists (li), otherwise formatting may be corrupted:

    Wrong Translate End Line Syntax - LightWrong Translate End Line Syntax - Dark

    The above should be written as:

    Correct Translate End Line Syntax - LightCorrect Translate End Line Syntax - Dark

  5. Empty Line for Line Breaks: Content needs an empty line to create line breaks. Without empty lines, content will render as continuous text:

    Wrong End Line Syntax - LightWrong End Line Syntax - Dark

    The above should be written as:

    Correct End Line Syntax - LightCorrect End Line Syntax - Dark

    Note: Lists (li) are not affected by this issue.

开发提示 ​

:::tip Markdown 解析问题 在编写文档时，请注意以下重要的解析规则：

  1. 语言块语法：对于特定语言的内容块，结尾只需要一个 :::：

    错误内容语法 - Light错误内容语法 - Dark

    上面的写法应该改为：

    正确内容语法 - Light正确内容语法 - Dark

    当遇到 :::en 时语言会自动切换。

  2. 标题语言指定：标题必须使用 { lang="en" } 语法，不能使用语言块：

    正确标题语法 - Light正确标题语法 - Dark

    不要使用：

    错误标题语法 - Light错误标题语法 - Dark

  3. 文本格式约定：为了方便在纯文本环境下的观察起见，在编写双语内容时请遵循先英文后中文的顺序。这样可以更容易在文本编辑器和版本控制系统中观察和导航文档结构。

  4. 结束块 ::: 前换行：结束块的 ::: 前最好换行，尤其是使用了列表（li），否则会被格式化乱掉：

    错误翻译结束行语法 - Light错误翻译结束行语法 - Dark

    上面的写法应该改为：

    正确翻译结束行语法 - Light正确翻译结束行语法 - Dark

  5. 内容换行需要空行：内容需要空一行才能换行。没有空行的话，内容会渲染成连续的文本：

    错误结束行语法 - Light错误结束行语法 - Dark

    上面的写法应该改为：

    正确结束行语法 - Light正确结束行语法 - Dark

    注意：列表（li）不涉及这个问题。

License ​

This documentation project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

  • Freedom to Use: You can use, modify, and distribute this documentation
  • Copyleft: Any derivative works must also be licensed under AGPL-3.0
  • Network Use: If you run a modified version on a server, you must provide the source code
  • Attribution: You must preserve copyright notices and license information

For the full license text, see the LICENSE file.

By contributing to this project, you agree that your contributions will be licensed under the same AGPL-3.0 license.

许可证与法律 ​

许可证 ​

本文档项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。

  • 使用自由：您可以使用、修改和分发此文档
  • Copyleft：任何衍生作品也必须采用 AGPL-3.0 许可证
  • 网络使用：如果您在服务器上运行修改版本，必须提供源代码
  • 署名：您必须保留版权声明和许可证信息

完整的许可证文本请参见 LICENSE 文件。

通过为本项目做出贡献，您同意您的贡献将采用相同的 AGPL-3.0 许可证。

Contributors

Edit this page on GitHub

Last updated: