You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@bifromq.apache.org by vi...@apache.org on 2026/08/13 01:58:28 UTC
(bifromq-sites) branch codex/phase-1-search-foundation created (now c62bf9bd)
This is an automated email from the ASF dual-hosted git repository.
visoar pushed a change to branch codex/phase-1-search-foundation
in repository https://gitbox.apache.org/repos/asf/bifromq-sites.git
at c62bf9bd docs: establish search discovery baseline
This branch includes the following new commits:
new c62bf9bd docs: establish search discovery baseline
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(bifromq-sites) 01/01: docs: establish search discovery baseline
Posted by vi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
visoar pushed a commit to branch codex/phase-1-search-foundation
in repository https://gitbox.apache.org/repos/asf/bifromq-sites.git
commit c62bf9bd0735eb9672e943dd5e5d56dbad721595
Author: Visoar Zhang <vi...@gmail.com>
AuthorDate: Thu Aug 13 09:58:20 2026 +0800
docs: establish search discovery baseline
---
.github/workflows/deploy.yml | 2 +
.../documentation_contribution.md | 10 ++-
docusaurus.config.ts | 47 +++++++++++++
package.json | 1 +
scripts/check-site-policy.mjs | 76 ++++++++++++++++++++++
static/google55353de668345094.html | 1 +
6 files changed, 136 insertions(+), 1 deletion(-)
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 7131e319..6af8d258 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -43,6 +43,8 @@ jobs:
run: pnpm run typecheck
- name: Build site
run: pnpm run build
+ - name: Check documentation and verification policy
+ run: pnpm run check:site-policy
- name: Copy .asf.yaml
run: cp .asf.yaml build/.asf.yaml
- name: Publish to asf-site
diff --git a/docs/contribution_guide/documentation_contribution.md b/docs/contribution_guide/documentation_contribution.md
index 95ac5d96..7e4088b4 100644
--- a/docs/contribution_guide/documentation_contribution.md
+++ b/docs/contribution_guide/documentation_contribution.md
@@ -16,7 +16,7 @@ Here are some ways you can help improve the documentation:
- Update outdated content
- Add new sections (e.g., feature usage, configuration examples, deployment tips)
- Improve the structure or navigation
-- Translate content (when relevant)
+- Improve English-language documentation and terminology
- Update or improve the project website
No contribution is too small — even fixing a broken link makes a difference!
@@ -56,6 +56,14 @@ BifroMQ’s documentation is hosted in the main [GitHub repository](https://gith
- Be consistent in tone (neutral and helpful).
- Link to relevant code or external references when useful.
+### Documentation Language and Versions
+
+The project currently maintains official documentation in English only. A localization proposal needs identified maintainers and reviewers, together with a sustainable update process, before localized pages are published as official documentation.
+
+The current release documentation is the primary, indexable documentation set. Version 3.3.x remains indexable as the latest historical 3.x reference and is clearly marked as unmaintained. Versions 3.2.x and earlier remain available for existing users, but are marked as archived and excluded from search indexing and the sitemap to avoid presenting outdated instructions as current guidance.
+
+Archived pages keep their version-specific URLs and must not be canonicalized to current documentation unless the content is verified to be equivalent.
+
### Need Help?
If you're unsure about what or how to contribute:
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 5c07c050..64abf7b8 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -18,6 +18,12 @@ const config: Config = {
url: `https://${projectName.toLowerCase()}.apache.org/`,
baseUrl: '/',
+ // English is the only documentation locale currently maintained by the project.
+ i18n: {
+ defaultLocale: 'en',
+ locales: ['en'],
+ },
+
onBrokenLinks: 'throw',
trailingSlash: true,
@@ -89,6 +95,47 @@ const config: Config = {
label: `${releaseVersion}`,
badge: true,
},
+ '3.3.x': {
+ label: '3.3.x (historical)',
+ banner: 'unmaintained',
+ badge: true,
+ },
+ '3.2.x': {
+ label: '3.2.x (archived)',
+ banner: 'unmaintained',
+ badge: true,
+ noIndex: true,
+ },
+ '3.1.x': {
+ label: '3.1.x (archived)',
+ banner: 'unmaintained',
+ badge: true,
+ noIndex: true,
+ },
+ '3.0.x': {
+ label: '3.0.x (archived)',
+ banner: 'unmaintained',
+ badge: true,
+ noIndex: true,
+ },
+ '2.1.x': {
+ label: '2.1.x (archived)',
+ banner: 'unmaintained',
+ badge: true,
+ noIndex: true,
+ },
+ '2.0.0': {
+ label: '2.0.0 (archived)',
+ banner: 'unmaintained',
+ badge: true,
+ noIndex: true,
+ },
+ '1.0.x': {
+ label: '1.0.x (archived)',
+ banner: 'unmaintained',
+ badge: true,
+ noIndex: true,
+ },
},
},
blog: {
diff --git a/package.json b/package.json
index 0e4a77e6..f01b3768 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
"docusaurus": "docusaurus",
"start": "NO_UPDATE_NOTIFIER=1 docusaurus start",
"build": "NO_UPDATE_NOTIFIER=1 docusaurus build",
+ "check:site-policy": "node scripts/check-site-policy.mjs",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
diff --git a/scripts/check-site-policy.mjs b/scripts/check-site-policy.mjs
new file mode 100644
index 00000000..f82d43b4
--- /dev/null
+++ b/scripts/check-site-policy.mjs
@@ -0,0 +1,76 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import {readFileSync, readdirSync, statSync} from 'node:fs';
+import {join} from 'node:path';
+
+const buildDir = new URL('../build/', import.meta.url).pathname;
+const archivedVersions = ['3.2.x', '3.1.x', '3.0.x', '2.1.x', '2.0.0', '1.0.x'];
+
+function fail(message) {
+ throw new Error(message);
+}
+
+function read(relativePath) {
+ return readFileSync(join(buildDir, relativePath), 'utf8');
+}
+
+function findHtmlFiles(directory) {
+ return readdirSync(directory).flatMap((entry) => {
+ const path = join(directory, entry);
+ return statSync(path).isDirectory()
+ ? findHtmlFiles(path)
+ : path.endsWith('.html')
+ ? [path]
+ : [];
+ });
+}
+
+const verification = read('google55353de668345094.html').trim();
+if (verification !== 'google-site-verification: google55353de668345094.html') {
+ fail('Google Search Console verification file is missing or invalid.');
+}
+
+const sitemap = read('sitemap.xml');
+if (!sitemap.includes('https://bifromq.apache.org/docs/3.3.x/')) {
+ fail('The latest historical 3.x documentation must remain in the sitemap.');
+}
+
+for (const version of archivedVersions) {
+ const versionUrl = `https://bifromq.apache.org/docs/${version}/`;
+ if (sitemap.includes(versionUrl)) {
+ fail(`Archived documentation ${version} must not be in the sitemap.`);
+ }
+
+ const versionDir = join(buildDir, 'docs', version);
+ const htmlFiles = findHtmlFiles(versionDir);
+ if (htmlFiles.length === 0) {
+ fail(`Archived documentation ${version} was not built.`);
+ }
+
+ for (const htmlFile of htmlFiles) {
+ const html = readFileSync(htmlFile, 'utf8');
+ if (!html.includes('name="robots" content="noindex, nofollow"')) {
+ fail(`Archived page is missing the Docusaurus noindex directive: ${htmlFile}`);
+ }
+ if (!html.includes('which is no longer actively maintained')) {
+ fail(`Archived page is missing the unmaintained notice: ${htmlFile}`);
+ }
+ }
+}
+
+console.log('Site policy checks passed.');
diff --git a/static/google55353de668345094.html b/static/google55353de668345094.html
new file mode 100644
index 00000000..d41008aa
--- /dev/null
+++ b/static/google55353de668345094.html
@@ -0,0 +1 @@
+google-site-verification: google55353de668345094.html