This is an automated email from the ASF dual-hosted git repository.
hcr pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/mahout.git
The following commit(s) were added to refs/heads/main by this push:
new 927044b49 docs: merge website/CONTRIBUTING.md into website/README.md,
add troubleshooting guide (#1134)
927044b49 is described below
commit 927044b49d48a49351249b72f39ead1ddf2bea52
Author: Tim Hsiung <[email protected]>
AuthorDate: Sat Mar 7 11:38:52 2026 +0800
docs: merge website/CONTRIBUTING.md into website/README.md, add
troubleshooting guide (#1134)
---
website/CONTRIBUTING.md | 71 -------------------------------------------------
website/README.md | 31 +++++++++++++--------
2 files changed, 20 insertions(+), 82 deletions(-)
diff --git a/website/CONTRIBUTING.md b/website/CONTRIBUTING.md
deleted file mode 100644
index e986b6517..000000000
--- a/website/CONTRIBUTING.md
+++ /dev/null
@@ -1,71 +0,0 @@
-<!--
-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.
--->
-
-# Contributing to the Apache Mahout Website
-
-This guide covers **website and documentation** development. For
repository-wide workflow (issues, branches, pull requests, pre-commit), see the
root [CONTRIBUTING.md](../CONTRIBUTING.md).
-
-## Prerequisites
-
-- Node.js and npm (for Docusaurus)
-
-## Quick Start
-
-From the **`website/`** directory:
-
-```bash
-npm install
-npm run start
-```
-
-This starts the dev server at `http://localhost:3000` with hot reload.
-
-## Documentation Source of Truth
-
-**Edit documentation in `/docs/`** (at repository root), **not** inside
`website/docs/`. The website syncs from `/docs/` at build and dev-server start.
-
-- **Source:** `/docs/` — edit here
-- **Synced:** `website/docs/` — generated; do not edit manually
-
-Sync manually if needed:
-
-```bash
-cd website
-npm run sync
-```
-
-## Common Tasks
-
-| Task | Command (from `website/`) |
-|------|---------------------------|
-| Local development | `npm run start` |
-| Production build | `npm run build` |
-| Sync docs from `/docs/` | `npm run sync` |
-| Create version snapshot (release) | `npm run docusaurus docs:version X.Y` |
-
-## Adding or Changing Docs
-
-1. Add or edit Markdown under **`/docs/`** (repo root).
-2. Update **`website/sidebars.ts`** if you add new pages or sections.
-3. Run `npm run sync` (or restart `npm run start`) to preview.
-
-Use **kebab-case** for file names and frontmatter `title` in each doc. See
[website/README.md](README.md) for sidebar config, images, math, and versioning.
-
-## References
-
-- [website/README.md](README.md) — Full website guide: sync, sidebars,
versioning, blog, deployment
-- [Docusaurus docs](https://docusaurus.io/docs)
diff --git a/website/README.md b/website/README.md
index 25f8248ba..08f908902 100644
--- a/website/README.md
+++ b/website/README.md
@@ -2,6 +2,11 @@
This website is built using [Docusaurus](https://docusaurus.io/), a modern
static website generator.
+## Prerequisites
+
+- Node.js
+- npm (for Docusaurus)
+
## Quick Start
```bash
@@ -10,7 +15,7 @@ npm install
npm run start
```
-This starts a local development server at `http://localhost:3000` with hot
reload.
+This starts a local development server at `http://localhost:3000` with hot
reload. The changes to the documentation will be reflected at
`http://localhost:3000/docs/next/`.
## Architecture
@@ -33,14 +38,14 @@ This starts a local development server at
`http://localhost:3000` with hot reloa
├── api.md, basic-gates.md... # API reference docs
└── adr/ # Architecture decisions
-/website-new/docs/ ← BUILD ARTIFACT (auto-synced, don't edit!)
+/website/docs/ ← BUILD ARTIFACT (auto-synced, don't edit!)
├── .gitignore # Only tracked file
└── [everything synced from /docs/]
```
### Sync Workflow
-The sync script copies `/docs/` to `website-new/docs/` at build time:
+The sync script copies `/docs/` to `website/docs/` at build time:
```bash
npm run sync # Manual sync
@@ -49,9 +54,9 @@ npm run build # Auto-syncs before building
```
**Important:**
-- Edit ALL documentation in `/docs/`, NOT in `website-new/docs/`
-- `website-new/docs/` is gitignored (except `.gitignore` itself)
-- Changes in `website-new/docs/` will be overwritten on next sync
+- Edit ALL documentation in `/docs/`, NOT in `website/docs/`
+- `website/docs/` is gitignored (except `.gitignore` itself)
+- Changes in `website/docs/` will be overwritten on next sync
## Adding New Documentation
@@ -71,7 +76,7 @@ Content here...
### 2. Add to Sidebar
-Edit `website-new/sidebars.ts`:
+Edit `website/sidebars.ts`:
```typescript
const sidebars: SidebarsConfig = {
@@ -125,7 +130,7 @@ sidebar_position: 1 # Optional: order in
auto-generated sidebars
## Adding Images
-1. Place images in `/docs/assets/` (for code docs) or
`website-new/static/img/` (for website)
+1. Place images in `/docs/assets/` (for code docs) or `website/static/img/`
(for website)
2. Reference in markdown:
```markdown
@@ -199,7 +204,7 @@ docs: {
## Blog Posts
-Blog posts live in `website-new/blog/`:
+Blog posts live in `website/blog/`:
```markdown
---
@@ -227,12 +232,16 @@ npm run serve # Serve production build locally
GitHub Actions automatically deploys to `asf-site` branch when changes are
pushed to `main`.
Triggers:
-- Changes to `website-new/**`
+- Changes to `website/**`
- Changes to `docs/**`
- Changes to `qdp/docs/**`
## Troubleshooting
+### Changes are not reflected in the development server
+
+Please ensure that you are looking at `http://localhost:3000/docs/next/`.
+
### Broken Links
The build will warn about broken links. Fix them in the source files
(`/docs/`).
@@ -253,7 +262,7 @@ Document IDs are derived from file paths:
## Project Structure
```
-website-new/
+website/
├── docusaurus.config.ts # Main configuration
├── sidebars.ts # Sidebar navigation
├── package.json
