From 0414be94fb4dd3eec73e54d1431e6031e61c3eb9 Mon Sep 17 00:00:00 2001 From: overtrue Date: Thu, 16 Jul 2026 13:58:34 +0800 Subject: [PATCH] docs: clear the pre-existing docs-check failures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make `npm run docs:check` pass cleanly: - Add a language to 13 unlabelled code fences (http for S3 request lines, bash for commands, text for output/URLs/trees) - Replace banned example values: mc.md endpoint 12.34.56.78 -> 192.168.1.100 with placeholder keys; mcp.md region cn-east-1 -> us-east-1 - Delete two vestigial concept index pages (concepts/index.md and concepts/principle/index.md) that duplicated the sidebar and, in the case of principle/index, listed unlinked placeholder bullets - docs-check: resolve a .md link when only the sibling .mdx exists (and vice versa), matching how FumaPress maps links by URL — fixes the three docker/index.mdx link reports docs-check now passes; build OK (295 pages). --- content/concepts/index.md | 13 ------------- content/concepts/principle/index.md | 12 ------------ content/developer/mc.md | 2 +- content/developer/mcp.md | 6 +++--- content/installation/docker/index.mdx | 6 +++--- content/integration/virtual.md | 6 +++--- content/management/bucket/creation.md | 2 +- content/management/bucket/deletion.md | 2 +- content/management/object/creation.md | 4 ++-- content/management/object/deletion.md | 2 +- scripts/docs-check.mjs | 9 +++++++-- 11 files changed, 22 insertions(+), 42 deletions(-) delete mode 100644 content/concepts/index.md delete mode 100644 content/concepts/principle/index.md diff --git a/content/concepts/index.md b/content/concepts/index.md deleted file mode 100644 index 7f8f121f..00000000 --- a/content/concepts/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "RustFS Architecture Design and Core Concepts Explained" -description: "This article introduces vocabulary frequently used in object storage, helping users quickly understand object storage" ---- - -This chapter contains the following content: - -- [RustFS Introduction](./introduction.md) -- [RustFS Design Architecture](./architecture.md) -- [Mainstream Storage Product Comparison](./comparison.md) -- [Common Terminology](./glossary.md) -- [Core Concepts](./principle/index.md) -- [Usage Limitations](./limit.md) \ No newline at end of file diff --git a/content/concepts/principle/index.md b/content/concepts/principle/index.md deleted file mode 100644 index a63d0845..00000000 --- a/content/concepts/principle/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "RustFS Core Concepts Explained" -description: "Detailed explanation of RustFS core concepts, including erasure coding, stripes, Data Scanner, data self-healing, etc. Allows users to have a deeper understanding of RustFS." ---- - -This chapter contains the following content: - -- [Erasure Coding](./erasure-coding.md) -- Stripes -- Data Scanner -- Data Self-healing -- Stripes \ No newline at end of file diff --git a/content/developer/mc.md b/content/developer/mc.md index 16e6221a..62a9d4c5 100644 --- a/content/developer/mc.md +++ b/content/developer/mc.md @@ -16,7 +16,7 @@ Prerequisites: First, configure an alias for RustFS using the `mc alias` command: ```bash -mc alias set rustfs http://12.34.56.78:9000 ACCESS_KEY SECRET_KEY +mc alias set rustfs http://192.168.1.100:9000 ``` Output: diff --git a/content/developer/mcp.md b/content/developer/mcp.md index d567ee19..3333db3e 100644 --- a/content/developer/mcp.md +++ b/content/developer/mcp.md @@ -166,7 +166,7 @@ Currently, mainstream AI IDEs such as Cursor, Windsurf, Trae, etc. all support M "env": { "AWS_ACCESS_KEY_ID": "rustfs_access_key", "AWS_SECRET_ACCESS_KEY": "rustfs_secret_key", - "AWS_REGION": "cn-east-1", + "AWS_REGION": "us-east-1", "AWS_ENDPOINT_URL": "rustfs_instance_url" } } @@ -182,7 +182,7 @@ If added successfully, you can list the [available tools](#️-available-tools) In Trae, you can use the corresponding tools by entering the corresponding prompts. For example, in Trae's chat dialog, enter: -``` +```text Please help me list the buckets in the current rustfs instance, thank you! ``` @@ -257,7 +257,7 @@ Deletes the specified RustFS bucket. The MCP server is built with a modular architecture: -``` +```text rustfs-mcp/ ├── src/ │ ├── main.rs # Entry point, CLI parsing and server initialization diff --git a/content/installation/docker/index.mdx b/content/installation/docker/index.mdx index 08661632..e6e32759 100644 --- a/content/installation/docker/index.mdx +++ b/content/installation/docker/index.mdx @@ -168,7 +168,7 @@ git clone https://github.com/rustfs/rustfs.git Running the command under root directory, -``` +```bash docker compose --profile observability up -d ``` @@ -200,7 +200,7 @@ Providing the necessary permissions. An initialization container is necessary to Started containers is as below, -``` +```text CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES c13c23fe3d9d rustfs/rustfs:latest "/entrypoint.sh rust…" 6 seconds ago Up 5 seconds (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server e3f4fc4a83a2 grafana/grafana:latest "/run.sh" 7 seconds ago Up 5 seconds 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp grafana @@ -217,7 +217,7 @@ docker compose -f docker-compose.yml up -d rustfs This way will only install and start `rustfs-server` service, namely rustfs container, -``` +```text docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e07121ecdd39 rustfs/rustfs:latest "/entrypoint.sh rust…" 2 seconds ago Up 1 second (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server diff --git a/content/integration/virtual.md b/content/integration/virtual.md index 99c38400..02a9ac4d 100644 --- a/content/integration/virtual.md +++ b/content/integration/virtual.md @@ -16,7 +16,7 @@ Path Style is the default. In Path Style, the bucket name follows the endpoint. Example (Bucket: `test`, Host: `rustfs.yourdomain.com`): -``` +```text http://rustfs.yourdomain.com/test ``` @@ -28,7 +28,7 @@ In Virtual Host Style, the bucket name is part of the domain. Example (Bucket: `test`, Host: `rustfs.yourdomain.com`): -``` +```text http://test.rustfs.yourdomain.com/ ``` @@ -51,7 +51,7 @@ RUSTFS_SERVER_DOMAINS = "rustfs.yourdomain.com:8000" This ensures that requests like: -``` +```text http://my-bucket.rustfs.yourdomain.com:8000/ ``` diff --git a/content/management/bucket/creation.md b/content/management/bucket/creation.md index 82df323b..5efe2f15 100644 --- a/content/management/bucket/creation.md +++ b/content/management/bucket/creation.md @@ -38,7 +38,7 @@ mc ls rustfs/bucket-creation-by-mc Create a bucket via API: -``` +```http PUT /{bucketName} HTTP/1.1 ``` diff --git a/content/management/bucket/deletion.md b/content/management/bucket/deletion.md index c7b504b8..90eb7a23 100644 --- a/content/management/bucket/deletion.md +++ b/content/management/bucket/deletion.md @@ -36,7 +36,7 @@ mc: Unable to list folder. Bucket `bucket-creation-by-mc` does not exist Delete a bucket via API: -``` +```http DELETE /{bucketName} HTTP/1.1 ``` diff --git a/content/management/object/creation.md b/content/management/object/creation.md index 603f5059..aa82ab35 100644 --- a/content/management/object/creation.md +++ b/content/management/object/creation.md @@ -50,7 +50,7 @@ Verify the upload in the RustFS Console. Upload a file via API: -``` +```http PUT /{bucketName}/{objectName} HTTP/1.1 ``` @@ -72,7 +72,7 @@ See [Object Deletion](./deletion.md). Use the following API for file deletion: -``` +```http DELETE /{bucketName}/{objectName} HTTP/1.1 ``` diff --git a/content/management/object/deletion.md b/content/management/object/deletion.md index d705e4d3..9cd993b9 100644 --- a/content/management/object/deletion.md +++ b/content/management/object/deletion.md @@ -35,7 +35,7 @@ Verify the deletion in the RustFS Console. Delete a file via API: -``` +```http DELETE /{bucketName}/{objectName} HTTP/1.1 ``` diff --git a/scripts/docs-check.mjs b/scripts/docs-check.mjs index d0567f37..a84f7dcb 100644 --- a/scripts/docs-check.mjs +++ b/scripts/docs-check.mjs @@ -127,12 +127,17 @@ for (const file of mdFiles) { } }); - // relative .md links: [text](path.md) — skip http(s), absolute, and anchors + // relative .md links: [text](path.md) — skip http(s), absolute, and anchors. + // A `.md` link also resolves if the sibling `.mdx` exists (FumaPress maps + // links by URL, not by on-disk extension), and vice versa. for (const m of text.matchAll(/\]\(([^)\s]+?\.mdx?)(?:#[^)]*)?\)/g)) { const target = m[1]; if (/^(https?:)?\/\//.test(target) || target.startsWith('/')) continue; const resolved = path.resolve(dir, decodeURIComponent(target)); - if (!fs.existsSync(resolved)) brokenLinks.push(`${rel(file)} -> ${target}`); + const alt = resolved.replace(/\.mdx$/, '.md').replace(/\.md$/, '.mdx'); + if (!fs.existsSync(resolved) && !fs.existsSync(alt)) { + brokenLinks.push(`${rel(file)} -> ${target}`); + } } // referenced images