# How to Report Bugs or Contribute Corrections to the hello-algo Documentation > Learn how to report bugs or contribute corrections to the hello-algo documentation. Follow our simple guide to submitting GitHub issues or pull requests for content updates. - Repository: [Yudong Jin/hello-algo](https://github.com/krahets/hello-algo) - Tags: how-to-guide - Published: 2026-02-25 --- **To report bugs or contribute corrections to the hello-algo documentation, open a GitHub issue for discussion or submit a pull request modifying the Markdown source files in the language-specific `*/docs/` directories, following the two-reviewer workflow defined in [`en/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/en/CONTRIBUTING.md) or [`ja/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/ja/CONTRIBUTING.md).** The **hello-algo** repository is an open-source algorithm learning resource built as a static site using **MkDocs**. If you spot typos, broken links, or unclear explanations, you can report bugs or contribute corrections to the hello-algo documentation through a structured GitHub workflow that ensures quality across multiple language versions. ## Understanding the Documentation Structure The documentation is organized as a MkDocs project with language-specific content directories. Each translation lives in its own folder with a `docs/` subdirectory containing the Markdown source files. - **English content**: `en/docs/` - **Japanese content**: `ja/docs/` - **Traditional Chinese content**: `zh-hant/docs/` The site configuration resides in [`mkdocs.yml`](https://github.com/krahets/hello-algo/blob/main/mkdocs.yml) at the repository root, while global style overrides are defined in [`overrides/stylesheets/extra.css`](https://github.com/krahets/hello-algo/blob/main/overrides/stylesheets/extra.css). ## Reporting Bugs in hello-algo Documentation For non-trivial bugs or content errors that require discussion, opening a GitHub issue is the preferred first step. Navigate to the **Issues** tab in the `krahets/hello-algo` repository. Create a new issue with a clear, descriptive title that identifies the problem. In the description, specify the exact file path and line number where the error occurs, using the format `en/docs/chapter_tree/binary_tree.md: line 42`. Include a brief explanation of the bug and, if applicable, suggest the correct information or wording. ## Contributing Corrections via Pull Request For straightforward fixes like typos, grammar corrections, or link updates, submit a pull request directly following the project's contribution workflow. ### Step 1: Review the Contribution Guidelines Before making changes, read the language-specific contribution guide. The English workflow is documented in [`en/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/en/CONTRIBUTING.md), while the Japanese workflow is in [`ja/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/ja/CONTRIBUTING.md). These files describe the translation validation pipeline, commit message conventions, and the requirement that **two reviewers must approve** any pull request before merging. ### Step 2: Fork and Branch Fork the repository on GitHub, then clone your fork locally and create a dedicated branch for your fix. ```bash # Clone your fork git clone https://github.com//hello-algo.git cd hello-algo # Create a feature branch git checkout -b fix-typo-binary-tree ``` ### Step 3: Edit the Markdown Source Locate and edit the specific Markdown file within the appropriate `*/docs/` directory. For example, to fix a typo in the English binary tree chapter, edit [`en/docs/chapter_tree/binary_tree.md`](https://github.com/krahets/hello-algo/blob/main/en/docs/chapter_tree/binary_tree.md). Make your corrections directly in the Markdown source, ensuring you preserve the existing formatting and frontmatter structure. ### Step 4: Local Preview with MkDocs (Optional) Verify your changes render correctly by running the local MkDocs server. ```bash # Install dependencies pip install mkdocs mkdocs-material # Serve the site locally mkdocs serve ``` Open `http://127.0.0.1:8000` in your browser to preview the documentation. This step is optional but recommended for structural changes or formatting fixes. ### Step 5: Commit and Push Stage your changes and commit with a descriptive message following conventional commit style. ```bash git add en/docs/chapter_tree/binary_tree.md git commit -m "fix: correct typo in binary_tree.md (line 42)" git push origin fix-typo-binary-tree ``` ### Step 6: Open the Pull Request Navigate to your fork on GitHub and click **"Compare & pull request"**. Target the `main` branch of `krahets/hello-algo`. In the PR description, reference any related issue (e.g., `Fixes #123`) and describe the correction. The PR template will prompt you to confirm you have followed the review checklist from the contribution guide. Note that **two reviewers must approve** your pull request before it can be merged into `main`. If reviewers request changes, address the feedback by pushing additional commits to your branch. ## Key Files for Contributors Understanding the repository layout helps you navigate the codebase efficiently. - **[`en/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/en/CONTRIBUTING.md)** – English contribution workflow and PR requirements - **[`ja/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/ja/CONTRIBUTING.md)** – Japanese contribution guidelines - **[`mkdocs.yml`](https://github.com/krahets/hello-algo/blob/main/mkdocs.yml)** – MkDocs site configuration and navigation structure - **`*/docs/`** – Language-specific Markdown source files (e.g., `en/docs/`, `ja/docs/`) - **[`overrides/stylesheets/extra.css`](https://github.com/krahets/hello-algo/blob/main/overrides/stylesheets/extra.css)** – Global CSS overrides affecting documentation appearance ## Summary - Report bugs or contribute corrections to the hello-algo documentation by opening GitHub issues for discussion or pull requests for direct fixes. - All documentation source files reside in language-specific `*/docs/` directories (e.g., `en/docs/`, `ja/docs/`). - Follow the contribution guidelines in [`en/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/en/CONTRIBUTING.md) or [`ja/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/ja/CONTRIBUTING.md), which require two reviewer approvals for every pull request. - Use MkDocs to preview changes locally by running `mkdocs serve` after installing `mkdocs-material`. ## Frequently Asked Questions ### Do I need to open an issue before submitting a pull request for a typo? No. For straightforward corrections like typos, broken links, or minor grammar fixes, you can submit a pull request directly without opening a separate issue. However, for structural changes, content inaccuracies, or controversial wording, opening an issue first is recommended to discuss the approach with maintainers. ### How many reviewers need to approve my documentation pull request? According to the workflow defined in [`en/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/en/CONTRIBUTING.md) and [`ja/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/ja/CONTRIBUTING.md), **two reviewers must approve** your pull request before it can be merged into the `main` branch. This requirement ensures quality and consistency across the multilingual documentation. ### Can I contribute corrections to non-English versions of the documentation? Yes. The repository maintains parallel documentation in multiple languages, each in its own directory (e.g., `ja/docs/` for Japanese, `zh-hant/docs/` for Traditional Chinese). Each language has its own contribution guide (e.g., [`ja/CONTRIBUTING.md`](https://github.com/krahets/hello-algo/blob/main/ja/CONTRIBUTING.md)) that may contain specific validation rules for that translation. ### What should I do if my change affects consistency across multiple languages? If your correction involves a concept, term, or code example that appears in multiple language versions, add a comment in your pull request highlighting the potential consistency impact. The maintainers can then assess whether the change should be propagated to other language directories or if language-specific variations are intentional.