This is an automated email from the ASF dual-hosted git repository. jin pushed a commit to branch update-doc in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph-doc.git
commit 9d20ef8118f5475568af4e89e44c728891e2e812 Author: imbajin <[email protected]> AuthorDate: Sat Jan 31 21:19:28 2026 +0800 docs: AGENTS.md, README.md, contribution.md Restructure and clarify repository documentation. AGENTS.md was rewritten and condensed into a practical agent/dev guide with development commands, prerequisites (Hugo Extended, Node.js v16+), content/structure overview, CI/CD notes, and troubleshooting tips. README.md was replaced with a bilingual (ZH/EN) homepage including a 3-step quickstart, repo layout, common commands, contributing requirements, contact info, and license. contribution.md was expanded with a PR checklist and clea [...] --- AGENTS.md | 203 ++++++++++++++++++++------------------------------------ README.md | 192 +++++++++++++++++++++++++++++++++++++---------------- contribution.md | 17 ++++- 3 files changed, 221 insertions(+), 191 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9108afe5..c4a05451 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,171 +1,110 @@ -# AI Development Agent Instructions +# AGENTS.md This file provides guidance to AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.) when working with code in this repository. ## Project Overview -This is the **Apache HugeGraph documentation website** repository (`hugegraph-doc`), built with Hugo static site generator using the Docsy theme. The site provides comprehensive documentation for the HugeGraph graph database system, including quickstart guides, API references, configuration guides, and contribution guidelines. +Apache HugeGraph documentation website built with Hugo static site generator and the Docsy theme. The site is bilingual (Chinese/English) and covers the complete HugeGraph graph database ecosystem. -The documentation is multilingual, supporting both **Chinese (cn)** and **English (en)** content. - -## Development Setup - -### Prerequisites - -1. **Hugo Extended** (v0.95.0 recommended, v0.102.3 used in CI) - - Must be the "extended" version (includes SASS/SCSS support) - - Download from: https://github.com/gohugoio/hugo/releases - - Install location: `/usr/bin` or `/usr/local/bin` - -2. **Node.js and npm** (v16+ as specified in CI) - -### Quick Start +## Development Commands ```bash -# Install npm dependencies (autoprefixer, postcss, postcss-cli) +# Install dependencies npm install -# Start local development server (with auto-reload) +# Start development server (auto-reload enabled) hugo server -# Custom server with different ip/port -hugo server -b http://127.0.0.1 -p 80 --bind=0.0.0.0 - # Build production site (output to ./public) hugo --minify -``` - -## Project Structure - -### Key Directories - -- **`content/`** - All documentation content in Markdown - - `content/cn/` - Chinese (simplified) documentation - - `content/en/` - English documentation - - Each language has parallel structure: `docs/`, `blog/`, `community/`, `about/` - -- **`themes/docsy/`** - The Docsy Hugo theme (submodule or vendored) - -- **`static/`** - Static assets (images, files) served directly - -- **`assets/`** - Assets processed by Hugo pipelines (SCSS, images for processing) - -- **`layouts/`** - Custom Hugo template overrides for the Docsy theme - -- **`public/`** - Generated site output (gitignored, created by `hugo` build) - -- **`dist/`** - Additional distribution files - -### Important Files - -- **`config.toml`** - Main site configuration - - Defines language settings (cn as default, en available) - - Menu structure and navigation - - Theme parameters and UI settings - - Currently shows version `0.13` - -- **`package.json`** - Node.js dependencies for CSS processing (postcss, autoprefixer) -- **`.editorconfig`** - Code style rules (UTF-8, LF line endings, spaces for indentation) +# Clean build +rm -rf public/ -- **`contribution.md`** - Contributing guide (Chinese/English mixed) +# Production build with garbage collection +HUGO_ENV="production" hugo --gc -- **`maturity.md`** - Project maturity assessment documentation +# Custom server configuration +hugo server -b http://127.0.0.1 -p 80 --bind=0.0.0.0 +``` -## Content Organization +## Prerequisites -Documentation is organized into major sections: +- **Hugo Extended** v0.95.0 recommended (v0.102.3 in CI) - must be the "extended" version for SASS/SCSS support +- **Node.js** v16+ and npm +- Download Hugo from: https://github.com/gohugoio/hugo/releases -- **`quickstart/`** - Getting started guides for HugeGraph components (Server, Loader, Hubble, Tools, Computer, AI) -- **`config/`** - Configuration documentation -- **`clients/`** - Client API documentation (Gremlin Console, RESTful API) -- **`guides/`** - User guides and tutorials -- **`performance/`** - Performance benchmarks and optimization -- **`language/`** - Query language documentation -- **`contribution-guidelines/`** - How to contribute to HugeGraph -- **`changelog/`** - Release notes and version history -- **`download/`** - Download links and instructions +## Architecture -## Common Tasks +``` +content/ +├── cn/ # Chinese documentation (default language) +│ ├── docs/ # Main documentation +│ ├── blog/ # Blog posts +│ ├── community/ +│ └── about/ +└── en/ # English documentation (parallel structure) + +themes/docsy/ # Docsy theme (submodule) +layouts/ # Custom template overrides +assets/ # Processed assets (SCSS, images) +static/ # Static files served directly +config.toml # Main site configuration +``` -### Building and Testing +### Content Structure -```bash -# Build for production (with minification) -hugo --minify +Documentation sections in `content/{cn,en}/docs/`: +- `quickstart/` - Getting started guides for HugeGraph components +- `config/` - Configuration documentation +- `clients/` - Client API documentation (Gremlin, RESTful) +- `guides/` - User guides and tutorials +- `performance/` - Benchmarks and optimization +- `language/` - Query language docs +- `contribution-guidelines/` - Contributing guides +- `changelog/` - Release notes +- `download/` - Download instructions -# Clean previous build -rm -rf public/ +## Key Configuration Files -# Build with specific environment -HUGO_ENV="production" hugo --gc -``` +- `config.toml` - Site-wide settings, language config, menu structure, version (currently 0.13) +- `package.json` - Node dependencies for CSS processing (postcss, autoprefixer, mermaid) +- `.editorconfig` - UTF-8, LF line endings, spaces for indentation -### Working with Content +## Working with Content When editing documentation: - 1. Maintain parallel structure between `content/cn/` and `content/en/` -2. Use Markdown format for all documentation files -3. Include front matter in each file (title, weight, description) -4. For translated content, ensure both Chinese and English versions are updated - -### Theme Customization - -- Global site config: `config.toml` (root directory) -- Theme-specific config: `themes/docsy/config.toml` -- Custom layouts: Place in `layouts/` to override theme defaults -- Custom styles: Modify files in `assets/` directory - -Refer to [Docsy documentation](https://www.docsy.dev/docs/) for theme customization details. +2. Use Markdown with Hugo front matter (title, weight, description) +3. For bilingual changes, update both Chinese and English versions +4. Include mermaid diagrams where appropriate (mermaid.js is available) ## Deployment -The site uses GitHub Actions for CI/CD (`.github/workflows/hugo.yml`): - -1. **Triggers**: On push to `master` branch or pull requests -2. **Build process**: - - Checkout with submodules (for themes) - - Setup Node v16 and Hugo v0.102.3 extended - - Run `npm i && hugo --minify` -3. **Deployment**: Publishes to `asf-site` branch (GitHub Pages) - -The deployed site is hosted as part of Apache HugeGraph's documentation infrastructure. - -## HugeGraph Architecture Context - -This documentation covers the complete HugeGraph ecosystem: - -- **HugeGraph-Server** - Core graph database engine with REST API -- **HugeGraph-Store** - Distributed storage engine with integrated computation -- **HugeGraph-PD** - Placement Driver for metadata management -- **HugeGraph-Toolchain**: - - Client (Java RESTful API client) - - Loader (data import tool) - - Hubble (web visualization platform) - - Tools (deployment and management utilities) -- **HugeGraph-Computer** - Distributed graph processing system (OLAP) -- **HugeGraph-AI** - Graph neural networks and LLM/RAG components +- **CI/CD**: GitHub Actions (`.github/workflows/hugo.yml`) +- **Trigger**: Push to `master` branch or pull requests +- **Build**: `npm i && hugo --minify` with Node v16 and Hugo v0.102.3 extended +- **Deploy**: Publishes to `asf-site` branch (GitHub Pages) +- **PR Requirements**: Include screenshots showing before/after changes -## Git Workflow +## HugeGraph Ecosystem Context -- **Main branch**: `master` (protected, triggers deployment) -- **PR requirements**: Include screenshots showing before/after changes in documentation -- **Commit messages**: Follow Apache commit conventions -- Always create a new branch from `master` for changes -- Deployment to `asf-site` branch is automated via GitHub Actions +This documentation covers: +- **HugeGraph-Server** - Core graph database with REST API +- **HugeGraph-Store** - Distributed storage engine +- **HugeGraph-PD** - Placement Driver for metadata +- **Toolchain** - Client, Loader, Hubble (web UI), Tools +- **HugeGraph-Computer** - Distributed OLAP graph processing +- **HugeGraph-AI** - GNN, LLM/RAG components ## Troubleshooting -**Error: "TOCSS: failed to transform scss/main.scss"** -- Cause: Using standard Hugo instead of Hugo Extended -- Solution: Install Hugo Extended version +**"TOCSS: failed to transform scss/main.scss"** +- Install Hugo Extended (not standard Hugo) -**Error: Module/theme not found** -- Cause: Git submodules not initialized -- Solution: `git submodule update --init --recursive` +**Theme/module not found** +- Run: `git submodule update --init --recursive` -**Build fails in CI but works locally** -- Check Hugo version match (CI uses v0.102.3) -- Ensure npm dependencies are installed -- Verify Node.js version (CI uses v16) +**CI build fails but works locally** +- Match Hugo version (v0.102.3) and Node.js (v16) +- Verify npm dependencies are installed diff --git a/README.md b/README.md index 18656cd5..45ec41a7 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,156 @@ +# Apache HugeGraph Documentation Website + [](https://deepwiki.com/apache/hugegraph-doc) +[](LICENSE) +[](https://gohugo.io/) + +--- + +**中文** | [English](#english-version) + +这是 [HugeGraph 官方文档网站](https://hugegraph.apache.org/docs/) 的**源代码仓库**。 + +如果你想查找 HugeGraph 数据库本身，请访问 [apache/hugegraph](https://github.com/apache/hugegraph)。 + +## 快速开始 + +只需 **3 步**即可在本地启动文档网站： + +**前置条件：** [Hugo Extended](https://github.com/gohugoio/hugo/releases) v0.95+ 和 Node.js v16+ + +```bash +# 1. 克隆仓库 +git clone https://github.com/apache/hugegraph-doc.git +cd hugegraph-doc + +# 2. 安装依赖 +npm install + +# 3. 启动开发服务器（支持热重载） +hugo server +``` + +打开 http://localhost:1313 预览网站。 + +> **常见问题：** 如果遇到 `TOCSS: failed to transform "scss/main.scss"` 错误， +> 说明你需要安装 Hugo **Extended** 版本，而不是标准版本。 + +## 仓库结构 -## Build/Test/Contribute to website +``` +hugegraph-doc/ +├── content/ # 📄 文档内容 (Markdown) +│ ├── cn/ # 🇨🇳 中文文档 +│ │ ├── docs/ # 主要文档目录 +│ │ │ ├── quickstart/ # 快速开始指南 +│ │ │ ├── config/ # 配置文档 +│ │ │ ├── clients/ # 客户端文档 +│ │ │ ├── guides/ # 使用指南 +│ │ │ └── ... +│ │ ├── blog/ # 博客文章 +│ │ └── community/ # 社区页面 +│ └── en/ # 🇺🇸 英文文档（与 cn/ 结构一致） +│ +├── themes/docsy/ # 🎨 Docsy 主题 (git submodule) +├── assets/ # 🖼️ 自定义资源 (fonts, images, scss) +├── layouts/ # 📐 Hugo 模板覆盖 +├── static/ # 📁 静态文件 +├── config.toml # ⚙️ 站点配置 +└── package.json # 📦 Node.js 依赖 +``` -Please visit the [contribution doc](./contribution.md) to get start, include theme/website description & settings~ +## 如何贡献 -### Summary +### 贡献流程 + +1. **Fork** 本仓库 +2. 基于 `master` 创建**新分支** +3. 修改文档内容 +4. 提交 **Pull Request**（附截图） + +### 重要说明 + +| 要求 | 说明 | +|------|------| +| **双语更新** | 修改内容时需**同时更新** `content/cn/` 和 `content/en/` | +| **PR 截图** | 提交 PR 时需附上修改**前后对比截图** | +| **Markdown** | 文档使用 Markdown 格式，带 Hugo front matter | + +### 详细指南 + +查看 [contribution.md](./contribution.md) 了解： +- 各平台 Hugo 安装方法 +- Docsy 主题定制 +- 翻译技巧 + +## 常用命令 + +| 命令 | 说明 | +|------|------| +| `hugo server` | 启动开发服务器（热重载） | +| `hugo --minify` | 构建生产版本到 `./public/` | +| `hugo server -p 8080` | 指定端口 | + +## 联系我们 + +- **问题反馈：** [GitHub Issues](https://github.com/apache/hugegraph-doc/issues) +- **邮件列表：** [[email protected]](mailto:[email protected])（[需先订阅](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/)） +- **Slack：** [ASF Slack](https://the-asf.slack.com/archives/C059UU2FJ23) +- **微信公众号：** Apache HugeGraph + +<img src="./assets/images/wechat.png" alt="WeChat QR Code" width="350"/> + +### 贡献者 + +感谢所有为 HugeGraph 文档做出贡献的人！ + +[](https://github.com/apache/hugegraph-doc/graphs/contributors) + +--- -Apache HugeGraph is an easy-to-use, efficient, general-purpose open-source graph database system -(Graph Database, [GitHub project address](https://github.com/hugegraph/hugegraph)), implementing the [Apache TinkerPop3](https://tinkerpop.apache.org) framework and fully compatible with the [Gremlin](https://tinkerpop.apache.org/gremlin.html) query language, -With complete toolchain components, it helps users easily build applications and products based on graph databases. HugeGraph supports fast import of more than 10 billion vertices and edges, and provides millisecond-level relational query capability (OLTP). -It also supports large-scale distributed graph computing (OLAP). +## English Version -Typical application scenarios of HugeGraph include deep relationship exploration, association analysis, path search, feature extraction, data clustering, community detection, knowledge graph, etc., and are applicable to business fields such as network security, telecommunication fraud, financial risk control, advertising recommendation, social network and intelligence Robots etc. +This is the **source code repository** for the [HugeGraph documentation website](https://hugegraph.apache.org/docs/). -### Features +For the HugeGraph database project, visit [apache/hugegraph](https://github.com/apache/hugegraph). -HugeGraph supports graph operations in online and offline environments, batch importing of data and efficient complex relationship analysis. It can seamlessly be integrated with big data platforms. -HugeGraph supports multi-user parallel operations. Users can enter Gremlin query statements and get graph query results in time. They can also call the HugeGraph API in user programs for graph analysis or queries. +### Quick Start -This system has the following features: +**Prerequisites:** [Hugo Extended](https://github.com/gohugoio/hugo/releases) v0.95+ and Node.js v16+ -- Ease of use: HugeGraph supports the Gremlin graph query language and a RESTful API, providing common interfaces for graph retrieval, and peripheral tools with complete functions to easily implement various graph-based query and analysis operations. -- Efficiency: HugeGraph has been deeply optimized in graph storage and graph computing, and provides a variety of batch import tools, which can easily complete the rapid import of tens of billions of data, and achieve millisecond-level response for graph retrieval through optimized queries. Supports simultaneous online real-time operations of thousands of users. -- Universal: HugeGraph supports the Apache Gremlin standard graph query language and the Property Graph standard graph modeling method, and supports graph-based OLTP and OLAP schemes. Integrate Apache Hadoop and Apache Spark big data platform. -- Scalable: supports distributed storage, multiple copies of data and horizontal expansion, built-in multiple back-end storage engines, and can easily expand the back-end storage engine through plug-ins. -- Open: HugeGraph code is open source (Apache 2 License), customers can modify and customize independently, and selectively give back to the open source community. +```bash +# 1. Clone repository +git clone https://github.com/apache/hugegraph-doc.git +cd hugegraph-doc -The functions of this system include but are not limited to: +# 2. Install dependencies +npm install -- Supports batch import of data from multiple data sources (including local files, HDFS files, MySQL databases and other data sources), and supports import of multiple file formats (including TXT, CSV, JSON and other formats) -- With a visual operation interface, it can be used for operation, analysis and display diagrams, reducing the threshold for users to use -- Optimized graph interface: shortest path (Shortest Path), K-step connected subgraph (K-neighbor), K-step to reach the adjacent point (K-out), personalized recommendation algorithm PersonalRank, etc. -- Implemented based on the Apache-TinkerPop3 framework, supports Gremlin graph query language -- Support attribute graph, attributes can be added to vertices and edges, and support rich attribute types -- Has independent schema metadata information, has powerful graph modeling capabilities, and facilitates third-party system integration -- Support multi-vertex ID strategy: support primary key ID, support automatic ID generation, support user-defined string ID, support user-defined digital ID -- The attributes of edges and vertices can be indexed to support precise query, range query, and full-text search -- The storage system adopts plug-in mode, supporting RocksDB, Cassandra, ScyllaDB, HBase, MySQL, PostgreSQL, Palo, and InMemory, etc. -- Integrate with big data systems such as Hadoop and Spark GraphX, and support Bulk Load operations -- Support high availability (HA), multiple copies of data, backup recovery, monitoring, etc. +# 3. Start development server (auto-reload) +hugo server +``` -### Modules +Open http://localhost:1313 to preview. -- [HugeGraph-Store]: HugeGraph-Store is a distributed storage engine to manage large-scale graph data by integrating storage and computation within a unified system. -- [HugeGraph-PD]: HugeGraph-PD (Placement Driver) manages metadata and coordinates storage nodes. -- [HugeGraph-Server](/docs/quickstart/hugegraph-server): HugeGraph-Server is the core part of the HugeGraph project, containing Core, Backend, API and other submodules; - - Core: Implements the graph engine, connects to the Backend module downwards, and supports the API module upwards; - - Backend: Implements the storage of graph data to the backend, supports backends including Memory, Cassandra, ScyllaDB, RocksDB, HBase, MySQL and PostgreSQL, users can choose one according to the actual situation; - - API: Built-in REST Server, provides RESTful API to users, and is fully compatible with Gremlin queries. (Supports distributed storage and computation pushdown) -- [HugeGraph-Toolchain](https://github.com/apache/hugegraph-toolchain): (Toolchain) - - [HugeGraph-Client](/docs/quickstart/hugegraph-client): HugeGraph-Client provides a RESTful API client for connecting to HugeGraph-Server, currently only the Java version is implemented, users of other languages can implement it themselves; - - [HugeGraph-Loader](/docs/quickstart/hugegraph-loader): HugeGraph-Loader is a data import tool based on HugeGraph-Client, which transforms ordinary text data into vertices and edges of the graph and inserts them into the graph database; - - [HugeGraph-Hubble](/docs/quickstart/hugegraph-hubble): HugeGraph-Hubble is HugeGraph's Web - visualization management platform, a one-stop visualization analysis platform, the platform covers the whole process from data modeling, to fast data import, to online and offline analysis of data, and unified management of the graph; - - [HugeGraph-Tools](/docs/quickstart/hugegraph-tools): HugeGraph-Tools is HugeGraph's deployment and management tool, including graph management, backup/recovery, Gremlin execution and other functions. -- [HugeGraph-Computer](/docs/quickstart/hugegraph-computer): HugeGraph-Computer is a distributed graph processing system (OLAP). - It is an implementation of [Pregel](https://kowshik.github.io/JPregel/pregel_paper.pdf). It can run on clusters such as Kubernetes/Yarn, and supports large-scale graph computing. -- [HugeGraph-AI](/docs/quickstart/hugegraph-ai): HugeGraph-AI is HugeGraph's independent AI - component, providing training and inference functions of graph neural networks, LLM/Graph RAG combination/Python-Client and other related components, continuously updating. +> **Troubleshooting:** If you see `TOCSS: failed to transform "scss/main.scss"`, +> install Hugo **Extended** version, not the standard version. -## Contributing +### Contributing -- Welcome to contribute to HugeGraph, please see [How to Contribute](https://hugegraph.apache.org/docs/contribution-guidelines/contribute/) for more information. -- Note: It's recommended to use [GitHub Desktop](https://desktop.github.com/) to greatly simplify the PR and commit process. -- Thank you to all the people who already contributed to HugeGraph! +1. **Fork** this repository +2. Create a **new branch** from `master` +3. Make your changes +4. Submit a **Pull Request** with screenshots -[](https://github.com/apache/incubator-hugegraph-doc/graphs/contributors) +**Requirements:** +- Update **BOTH** `content/cn/` and `content/en/` +- Include **before/after screenshots** in PR +- Use Markdown with Hugo front matter -### Contact Us +See [contribution.md](./contribution.md) for detailed instructions. --- -- [GitHub Issues](https://github.com/apache/incubator-hugegraph-doc/issues): Feedback on usage issues and functional requirements (quick response) -- Feedback Email: [[email protected]](mailto:[email protected]) ([subscriber](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/) only) -- Security Email: [[email protected]](mailto:[email protected]) (Report SEC problems) -- Slack: [ASF Online Channel](https://the-asf.slack.com/archives/C059UU2FJ23) -- WeChat public account: Apache HugeGraph, welcome to scan this QR code to follow us. +## License - <img src="./assets/images/wechat.png" alt="QR png" width="350"/> +[Apache License 2.0](LICENSE) diff --git a/contribution.md b/contribution.md index 9b59ab13..d736b79b 100644 --- a/contribution.md +++ b/contribution.md @@ -1,4 +1,19 @@ -# How to help us (如何参与) +# Contribution Guide - Detailed Reference + +> **快速开始请看 [README.md](./README.md)**，这里是详细的参考文档。 + +## PR 检查清单 + +提交 Pull Request 前请确认： + +- [ ] 本地构建并验证了修改效果 +- [ ] 同时更新了中文 (`content/cn/`) 和英文 (`content/en/`) 版本 +- [ ] PR 描述中包含修改前后的截图对比 +- [ ] 如有相关 Issue，已在 PR 中关联 + +--- + +## How to help us (如何参与) 1. 在本地 3 步快速构建官网环境，启动起来看下目前效果 (Auto reload) 2. 先 fork 仓库，然后基于 `master` 创建一个**新的**分支，修改完成后提交 PR ✅ (请在 PR 内**截图**对比一下修改**前后**的效果 & 简要说明，感谢)
