From f7c808383f86dfb834065bfa81de29129846d10c Mon Sep 17 00:00:00 2001 From: writinwaters <93570324+writinwaters@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:48:48 +0800 Subject: [PATCH] Docs: Refactored documentation (#13340) ### What problem does this PR solve? Refactored documentation. ### Type of change - [x] Documentation Update --- docs/administrator/_category_.json | 11 +++++++++++ docs/{guides => administrator}/admin/_category_.json | 6 +++--- docs/{guides => administrator}/admin/admin_service.md | 0 docs/{guides => administrator}/admin/admin_ui.md | 1 - docs/{guides => administrator}/admin/ragflow_cli.md | 0 docs/{ => administrator}/configurations.md | 4 ++-- .../migrate_to_single_bucket_mode.md | 2 +- .../migration/_category_.json | 6 +++--- .../migration/migrate_from_docker_compose.md | 0 docs/{guides => administrator}/tracing.mdx | 2 +- docs/{guides => administrator}/upgrade_ragflow.mdx | 2 +- docs/contribution/_category_.json | 11 ----------- docs/develop/_category_.json | 2 +- docs/develop/build_docker_image.mdx | 2 +- docs/{contribution => develop}/contributing.md | 2 +- docs/develop/launch_ragflow_from_source.md | 4 ++-- docs/develop/mcp/_category_.json | 2 +- docs/faq.mdx | 4 ++-- docs/guides/_category_.json | 4 ++-- docs/guides/models/_category_.json | 2 +- docs/guides/models/llm_api_key_setup.md | 2 +- .../models}/supported_models.mdx | 0 docs/quickstart.mdx | 6 +++--- docs/release_notes.md | 8 ++++---- 24 files changed, 41 insertions(+), 42 deletions(-) create mode 100644 docs/administrator/_category_.json rename docs/{guides => administrator}/admin/_category_.json (53%) rename docs/{guides => administrator}/admin/admin_service.md (100%) rename docs/{guides => administrator}/admin/admin_ui.md (98%) rename docs/{guides => administrator}/admin/ragflow_cli.md (100%) rename docs/{ => administrator}/configurations.md (99%) rename docs/{develop => administrator}/migrate_to_single_bucket_mode.md (99%) rename docs/{guides => administrator}/migration/_category_.json (51%) rename docs/{guides => administrator}/migration/migrate_from_docker_compose.md (100%) rename docs/{guides => administrator}/tracing.mdx (99%) rename docs/{guides => administrator}/upgrade_ragflow.mdx (99%) delete mode 100644 docs/contribution/_category_.json rename docs/{contribution => develop}/contributing.md (98%) rename docs/{references => guides/models}/supported_models.mdx (100%) diff --git a/docs/administrator/_category_.json b/docs/administrator/_category_.json new file mode 100644 index 0000000000..2579af6404 --- /dev/null +++ b/docs/administrator/_category_.json @@ -0,0 +1,11 @@ +{ + "label": "Administrator guides", + "position": 3, + "link": { + "type": "generated-index", + "description": "Guides for system administrtors" + }, + "customProps": { + "sidebarIcon": "LucidComputer" + } +} diff --git a/docs/guides/admin/_category_.json b/docs/administrator/admin/_category_.json similarity index 53% rename from docs/guides/admin/_category_.json rename to docs/administrator/admin/_category_.json index fa6d832fc8..c05f2e4800 100644 --- a/docs/guides/admin/_category_.json +++ b/docs/administrator/admin/_category_.json @@ -1,9 +1,9 @@ { - "label": "Administration", - "position": 6, + "label": "Admin service", + "position": 3, "link": { "type": "generated-index", - "description": "RAGFlow administration" + "description": "RAGFlow administration service" }, "customProps": { "categoryIcon": "LucideUserCog" diff --git a/docs/guides/admin/admin_service.md b/docs/administrator/admin/admin_service.md similarity index 100% rename from docs/guides/admin/admin_service.md rename to docs/administrator/admin/admin_service.md diff --git a/docs/guides/admin/admin_ui.md b/docs/administrator/admin/admin_ui.md similarity index 98% rename from docs/guides/admin/admin_ui.md rename to docs/administrator/admin/admin_ui.md index 9584bb8cfc..ae90bb9738 100644 --- a/docs/guides/admin/admin_ui.md +++ b/docs/administrator/admin/admin_ui.md @@ -32,7 +32,6 @@ The service status page displays of all services within the RAGFlow system. - **Extra Info**: Display additional configuration information of a service in a dialog. - **Service Details**: Display detailed status information of a service in a dialog. According to service's type, a service's status information could be displayed as a plain text, a key-value data list, a data table or a bar chart. - ### User management The user management page provides comprehensive tools for managing all users in the RAGFlow system. diff --git a/docs/guides/admin/ragflow_cli.md b/docs/administrator/admin/ragflow_cli.md similarity index 100% rename from docs/guides/admin/ragflow_cli.md rename to docs/administrator/admin/ragflow_cli.md diff --git a/docs/configurations.md b/docs/administrator/configurations.md similarity index 99% rename from docs/configurations.md rename to docs/administrator/configurations.md index ca7e67e29e..7704269626 100644 --- a/docs/configurations.md +++ b/docs/administrator/configurations.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 0 slug: /configurations sidebar_custom_props: { sidebarIcon: LucideCog @@ -111,7 +111,7 @@ If you cannot download the RAGFlow Docker image, try the following mirrors. - For the `nightly` edition: - `RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly` or, - `RAGFLOW_IMAGE=infiniflow-registry.cn-shanghai.cr.aliyuncs.com/infiniflow/ragflow:nightly`. -::: + ::: ### Embedding service diff --git a/docs/develop/migrate_to_single_bucket_mode.md b/docs/administrator/migrate_to_single_bucket_mode.md similarity index 99% rename from docs/develop/migrate_to_single_bucket_mode.md rename to docs/administrator/migrate_to_single_bucket_mode.md index de7c8fe873..bb81ecb49e 100644 --- a/docs/develop/migrate_to_single_bucket_mode.md +++ b/docs/administrator/migrate_to_single_bucket_mode.md @@ -1,5 +1,5 @@ --- -sidebar_position: 20 +sidebar_position: 15 slug: /migrate_to_single_bucket_mode --- diff --git a/docs/guides/migration/_category_.json b/docs/administrator/migration/_category_.json similarity index 51% rename from docs/guides/migration/_category_.json rename to docs/administrator/migration/_category_.json index 1099886f2e..081b453109 100644 --- a/docs/guides/migration/_category_.json +++ b/docs/administrator/migration/_category_.json @@ -1,9 +1,9 @@ { - "label": "Migration", - "position": 5, + "label": "Data backup and migration", + "position": 2, "link": { "type": "generated-index", - "description": "RAGFlow migration guide" + "description": "Data backup and migration guide" }, "customProps": { "categoryIcon": "LucideArrowRightLeft" diff --git a/docs/guides/migration/migrate_from_docker_compose.md b/docs/administrator/migration/migrate_from_docker_compose.md similarity index 100% rename from docs/guides/migration/migrate_from_docker_compose.md rename to docs/administrator/migration/migrate_from_docker_compose.md diff --git a/docs/guides/tracing.mdx b/docs/administrator/tracing.mdx similarity index 99% rename from docs/guides/tracing.mdx rename to docs/administrator/tracing.mdx index 13cf99874b..c9b4221e14 100644 --- a/docs/guides/tracing.mdx +++ b/docs/administrator/tracing.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 5 slug: /tracing sidebar_custom_props: { categoryIcon: LucideLocateFixed diff --git a/docs/guides/upgrade_ragflow.mdx b/docs/administrator/upgrade_ragflow.mdx similarity index 99% rename from docs/guides/upgrade_ragflow.mdx rename to docs/administrator/upgrade_ragflow.mdx index ef43384ddc..bb80a920a0 100644 --- a/docs/guides/upgrade_ragflow.mdx +++ b/docs/administrator/upgrade_ragflow.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 1 slug: /upgrade_ragflow sidebar_custom_props: { categoryIcon: LucideArrowBigUpDash diff --git a/docs/contribution/_category_.json b/docs/contribution/_category_.json deleted file mode 100644 index a9bd348a8c..0000000000 --- a/docs/contribution/_category_.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "label": "Contribution", - "position": 8, - "link": { - "type": "generated-index", - "description": "Miscellaneous contribution guides." - }, - "customProps": { - "sidebarIcon": "LucideHandshake" - } -} diff --git a/docs/develop/_category_.json b/docs/develop/_category_.json index c80693175f..e2556b4d21 100644 --- a/docs/develop/_category_.json +++ b/docs/develop/_category_.json @@ -1,5 +1,5 @@ { - "label": "Developers", + "label": "Developer guides", "position": 4, "link": { "type": "generated-index", diff --git a/docs/develop/build_docker_image.mdx b/docs/develop/build_docker_image.mdx index 6cb2dede43..ad4d264f7d 100644 --- a/docs/develop/build_docker_image.mdx +++ b/docs/develop/build_docker_image.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 4 slug: /build_docker_image sidebar_custom_props: { categoryIcon: LucidePackage diff --git a/docs/contribution/contributing.md b/docs/develop/contributing.md similarity index 98% rename from docs/contribution/contributing.md rename to docs/develop/contributing.md index 39b5e1a550..e3f910672c 100644 --- a/docs/contribution/contributing.md +++ b/docs/develop/contributing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 20 slug: /contributing sidebar_custom_props: { categoryIcon: LucideBookA diff --git a/docs/develop/launch_ragflow_from_source.md b/docs/develop/launch_ragflow_from_source.md index c193e2be37..22f127f34c 100644 --- a/docs/develop/launch_ragflow_from_source.md +++ b/docs/develop/launch_ragflow_from_source.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 slug: /launch_ragflow_from_source sidebar_custom_props: { categoryIcon: LucideMonitorPlay @@ -90,7 +90,7 @@ docker compose -f docker/docker-compose-base.yml up -d ``` 3. **Optional:** If you cannot access HuggingFace, set the HF_ENDPOINT environment variable to use a mirror site: - + ```bash export HF_ENDPOINT=https://hf-mirror.com ``` diff --git a/docs/develop/mcp/_category_.json b/docs/develop/mcp/_category_.json index eb7b1444aa..aa67c45a95 100644 --- a/docs/develop/mcp/_category_.json +++ b/docs/develop/mcp/_category_.json @@ -1,6 +1,6 @@ { "label": "MCP", - "position": 40, + "position": 2, "link": { "type": "generated-index", "description": "Guides and references on accessing RAGFlow's datasets via MCP." diff --git a/docs/faq.mdx b/docs/faq.mdx index cc7ab374b5..965aa16dab 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 20 slug: /faq sidebar_custom_props: { sidebarIcon: LucideCircleQuestionMark @@ -445,7 +445,7 @@ See [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md). ### How to upgrade RAGFlow? -See [Upgrade RAGFlow](./guides/upgrade_ragflow.mdx) for more information. +See [Upgrade RAGFlow](./administrator/upgrade_ragflow.mdx) for more information. --- diff --git a/docs/guides/_category_.json b/docs/guides/_category_.json index 18f4890a98..a5551f8b8b 100644 --- a/docs/guides/_category_.json +++ b/docs/guides/_category_.json @@ -1,9 +1,9 @@ { - "label": "Guides", + "label": "User guides", "position": 3, "link": { "type": "generated-index", - "description": "Guides for RAGFlow users and developers." + "description": "Guides for RAGFlow users." }, "customProps": { "sidebarIcon": "LucideBookMarked" diff --git a/docs/guides/models/_category_.json b/docs/guides/models/_category_.json index b4a996b4fa..08f6f4ddf3 100644 --- a/docs/guides/models/_category_.json +++ b/docs/guides/models/_category_.json @@ -1,6 +1,6 @@ { "label": "Models", - "position": -1, + "position": 8, "link": { "type": "generated-index", "description": "Guides on model settings." diff --git a/docs/guides/models/llm_api_key_setup.md b/docs/guides/models/llm_api_key_setup.md index d2cf67597c..704d31e395 100644 --- a/docs/guides/models/llm_api_key_setup.md +++ b/docs/guides/models/llm_api_key_setup.md @@ -11,7 +11,7 @@ An API key is required for RAGFlow to interact with an online AI model. This gui ## Get model API key -RAGFlow supports most mainstream LLMs. Please refer to [Supported Models](../../references/supported_models.mdx) for a complete list of supported models. You will need to apply for your model API key online. Note that most LLM providers grant newly-created accounts trial credit, which will expire in a couple of months, or a promotional amount of free quota. +RAGFlow supports most mainstream LLMs. Please refer to [Supported Models](../../guides/models/supported_models.mdx) for a complete list of supported models. You will need to apply for your model API key online. Note that most LLM providers grant newly-created accounts trial credit, which will expire in a couple of months, or a promotional amount of free quota. :::note If you find your online LLM is not on the list, don't feel disheartened. The list is expanding, and you can [file a feature request](https://github.com/infiniflow/ragflow/issues/new?assignees=&labels=feature+request&projects=&template=feature_request.yml&title=%5BFeature+Request%5D%3A+) with us! Alternatively, if you have customized or locally-deployed models, you can [bind them to RAGFlow using Ollama, Xinference, or LocalAI](./deploy_local_llm.mdx). diff --git a/docs/references/supported_models.mdx b/docs/guides/models/supported_models.mdx similarity index 100% rename from docs/references/supported_models.mdx rename to docs/guides/models/supported_models.mdx diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index e1de5fe184..21e3fd4b90 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -1,11 +1,11 @@ --- -sidebar_position: 0 +sidebar_position: 2 slug: / sidebar_custom_props: { sidebarIcon: LucideRocket } --- -# Get started +# Quickstart import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import APITable from '@site/src/components/APITable'; @@ -249,7 +249,7 @@ This section provides instructions on setting up the RAGFlow server on Linux. If ## Configure LLMs -RAGFlow is a RAG engine and needs to work with an LLM to offer grounded, hallucination-free question-answering capabilities. RAGFlow supports most mainstream LLMs. For a complete list of supported models, please refer to [Supported Models](./references/supported_models.mdx). +RAGFlow is a RAG engine and needs to work with an LLM to offer grounded, hallucination-free question-answering capabilities. RAGFlow supports most mainstream LLMs. For a complete list of supported models, please refer to [Supported Models](./guides/models/supported_models.mdx). :::note RAGFlow also supports deploying LLMs locally using Ollama, Xinference, or LocalAI, but this part is not covered in this quick start guide. diff --git a/docs/release_notes.md b/docs/release_notes.md index 6e6319dd25..fb889add24 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 1 slug: /release_notes sidebar_custom_props: { sidebarIcon: LucideClipboardPenLine @@ -734,7 +734,7 @@ From this release onwards, **service_config.yaml.template** replaces **service_c This approach eliminates the need to manually update **service_config.yaml** after making changes to **.env**, facilitating dynamic environment configurations. :::danger IMPORTANT -Ensure that you [upgrade **both** your code **and** Docker image to this release](https://ragflow.io/docs/dev/upgrade_ragflow#upgrade-ragflow-to-the-most-recent-officially-published-release) before trying this new approach. +Ensure that you [upgrade **both** your code **and** Docker image to this release](./administrator/upgrade_ragflow.mdx#upgrade-ragflow-to-the-most-recent-officially-published-release) before trying this new approach. ::: ### API changes @@ -812,13 +812,13 @@ The default Docker image edition is `nightly-slim`. The following list clarifies - `nightly`: The full edition of the most recent tested Docker image. - `v0.12.0`: The full edition of the most recent **officially released** Docker image. -See [Upgrade RAGFlow](https://ragflow.io/docs/dev/upgrade_ragflow) for instructions on upgrading. +See [Upgrade RAGFlow](./administrator/upgrade_ragflow.mdx) for instructions on upgrading. ### Documentation #### Added documents -- [Upgrade RAGFlow](https://ragflow.io/docs/dev/upgrade_ragflow) +- [Upgrade RAGFlow](./administrator/upgrade_ragflow.mdx) ## v0.11.0