Documentation

The aMule documentation is maintained as Markdown files in the amule-org.github.io repository and published with Docusaurus v3.

Repository Structure

amule-org.github.io/
├── docs/                        # English documentation (source of truth)
│   ├── index.md                 # Docs landing page
│   ├── quickstart-guide.md
│   ├── manual/                  # User Manual (install, configure, use, troubleshoot, FAQ)
│   ├── developer/               # Developer Guide
│   ├── p2p-networks/            # eD2k & Kademlia protocol reference
│   └── contributing/
├── blog/                        # Blog posts
├── changelog/                   # Changelog (per-version release notes)
├── i18n/
│   └── es/                      # Spanish translations
│       ├── code.json            # UI strings (navbar, sidebar labels, etc.)
│       └── docusaurus-plugin-content-docs/current/
│           └── ...              # Mirrors docs/ structure with translated content
├── static/
│   └── img/
│       └── docs/                # Images used in documentation pages
├── src/
│   ├── pages/                   # Homepage (index.tsx) and Download page (download.tsx)
│   └── components/              # Homepage section components
├── sidebars.ts                  # Sidebar navigation structure
└── docusaurus.config.ts         # Site configuration

Adding or Editing a Page

Prerequisites

Node.js ≥ 24 is required. Install dependencies once after cloning:

git clone https://github.com/amule-org/amule-org.github.io.git
cd amule-org.github.io
npm install

Development Server

npm run start

This starts a local server at http://localhost:3000 with live reload. Changes to Markdown files are reflected immediately without rebuilding.

not

The local dev server does not include the full-text search index. Search only works in the production build (npm run build + npm run serve).

Editing an Existing Page

Open the relevant .md file under docs/.
Edit the content using standard Markdown (GitHub-flavored, rendered with CommonMark).
Verify your changes look correct in the dev server.
Commit and open a pull request.

Adding a New Page

Create a new .md file in the appropriate docs/ subfolder.
Add a front-matter block at the top of the file:
```
---
id: my-page
title: My Page Title
---
```
The id must be unique within its folder and match the filename (without extension).

// Example: adding 'developer/my-page' to the Developer Guide category
{
  type: 'category',
  label: 'Developer Guide',
  items: [
    'developer/my-page',   // ← add this line
    ...
  ],
}

Run npm run build to verify there are no broken links or build errors before submitting the pull request.

Adding a New Category (Subsection)

To add a new subcategory with its own landing page:

Create a new folder under docs/ (e.g. docs/developer/new-section/).
Create an index.md inside it with the category title.

Add the category to sidebars.ts:

{
  type: 'category',
  label: 'New Section',
  link: { type: 'doc', id: 'developer/new-section/index' },
  items: [
    'developer/new-section/page-one',
    'developer/new-section/page-two',
  ],
}

Writing Guidelines

Tone and Style

Write in clear, technical English. The audience is software users and developers familiar with technical terminology.
Use precise terms. Prefer "aMule terminates with a segmentation fault" over "aMule crashes".
Keep paragraphs short and focused. Use headings to structure long pages.
Do not use emojis in documentation.

Code Blocks

Use fenced code blocks with a language identifier for syntax highlighting:

```sh
cmake -B build -DBUILD_DAEMON=YES
cmake --build build -j"$(nproc)"
```

Use sh for shell commands, cpp for C++, py for Python, ini for configuration files, and so on.

Admonitions

Docusaurus supports the following admonition types:

:::note
Supplementary information that is useful but not critical.
:::

:::tip
A helpful suggestion or best practice.
:::

:::info
Context or background that helps the reader understand.
:::

:::warning
Something the reader must be careful about.
:::

:::danger
An action that can cause data loss, security problems, or other serious consequences.
:::

Images

Place images in static/img/docs/ and reference them as:

![Alt text](/img/docs/image-name.png)

All images must have meaningful alt text for accessibility. Documentation images should be in PNG format and placed inside the static/img/docs/ folder. Before committing them to git, optimize them and strip their metadata with optipng:

optipng -strip all *.png

Click-to-zoom is applied automatically — always write images in plain Markdown as shown above. A custom remark plugin (plugins/remark-zoom-large-images.js) inspects every image at build time and lets readers click to enlarge only the large ones — those with a real width of 850px or more (wider than the ~750px content column, so the browser downscales them). Icons, thumbnails and narrow dialogs are left untouched.

Always reference images in Markdown rather than with a hardcoded HTML <img> tag: Docusaurus validates Markdown image paths and fails the build if a referenced file is missing, but it does not check paths inside HTML <img> tags.

Links

Internal links — use relative paths to other .md files:

[Compilation guide](../compilation/index.md)

External links — use full URLs:

[GitHub repository](https://github.com/amule-org/amule)

Links to generated files (feeds, sitemaps) — use the pathname:// protocol to bypass the broken-link checker:

[Atom feed](pathname:///blog/atom.xml)

Terminology

Use consistent terminology throughout the documentation:

Preferred	Avoid
aMule (project name)	`Amule`, `AMule`, `amule` (when naming the project)
`amule` (binary / module)	`aMule`, `AMule` (in code or command contexts)
`amuled`	`AMuled`, `amule daemon`
`amulegui`	`AMuleGUI`
`amuleweb`	`AMuleWeb`, `amule web`
`amulecmd`	`AMuleCMD`, `amule cmd`
eD2k	ed2k (in prose)
Kademlia	kad (in prose)
High ID / Low ID	HighID, LowID, highid

Translations

This section covers translating the website documentation into another language. To translate the aMule application interface or the man pages, see the Translations guide instead.

The default locale is English (en). The additional locales are Spanish (es), French (fr), and Turkish (tr).

Adding or Updating a Translation

Documentation translations live in i18n/es/docusaurus-plugin-content-docs/current/. The folder structure mirrors docs/.

After adding a new English page, run:

npm run write-translations -- --locale es

This adds any new translation keys and preserves existing ones. Then translate the new content.

Adding a New Locale

To add a language beyond the existing ones:

i18n: {
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],   // add your locale code here
  localeConfigs: {
    fr: {label: 'Français'},
  },
},

Add the same locale code to the language array of the @easyops-cn/docusaurus-search-local theme in the same file:
```
themes: [
  [
    require.resolve('@easyops-cn/docusaurus-search-local'),
    {
      language: ['en', 'es', 'fr'],   // add your locale code here
      // ...
    },
  ],
],
```
not
The search plugin uses the language code for tokenization. Check its supported languages list — if your locale is not supported, omit it from the language array and the search index falls back to basic tokenization.
Generate the translation files and translate them as described above.
Preview the new locale locally:
```
npm run start -- --locale fr
```

UI Strings

React component strings (navbar, sidebar labels, homepage text) are in i18n/es/code.json. Each entry has a message field (translate this) and a description field (context for the translator — do not translate this).

Translation Fidelity

Translations must faithfully reflect the English original. Do not paraphrase or simplify. Technical terms (hash, changelog, peer, release, etc.) should remain in English when a translated equivalent would be less precise or less commonly used.

Translating with Weblate

Website translations are managed with Weblate. See the Weblate guide for the base files, components, and workflow.

Submitting a Contribution

Fork the repository on GitHub.
Create a feature branch: git checkout -b docs/my-improvement
Make your changes, verify with npm run build.
Commit with a clear, descriptive message.
Open a pull request against the main branch.

The pull request description should explain what was changed and why. For substantial additions, a brief summary of the content helps reviewers.

Repository Structure​

Adding or Editing a Page​

Prerequisites​

Development Server​

Editing an Existing Page​

Adding a New Page​

Adding a New Category (Subsection)​

Writing Guidelines​

Tone and Style​

Code Blocks​

Admonitions​

Images​

Links​

Terminology​

Translations​

Adding or Updating a Translation​

Adding a New Locale​

UI Strings​

Translation Fidelity​

Translating with Weblate​

Submitting a Contribution​