OrcaSlicer_WIKI/developer_reference/how_to_wiki.md

# How to Contribute to the Wiki

This guide explains how to contribute to the OrcaSlicer wiki.

OrcaSlicer's wiki is generated automatically from the files in the [OrcaSlicer WIKI repository](https://github.com/OrcaSlicer/OrcaSlicer_WIKI).  
To suggest small changes or improvements, please [open an issue in that repository](https://github.com/OrcaSlicer/OrcaSlicer_WIKI/issues).  
If you prefer to make the edits yourself, follow this guide for best practices when creating a pull request (PR).

We encourage developers and users to contribute by updating existing pages and adding new content. This helps keep the documentation accurate and useful.  
When adding new features, consider updating the wiki so users can access the latest guidance.

- [Wiki Structure](#wiki-structure)
    - [Home](#home)
        - [Index and Navigation](#index-and-navigation)
    - [File Naming and Organization](#file-naming-and-organization)
- [Orca to Wiki Redirection](#orca-to-wiki-redirection)
- [Formatting and Style](#formatting-and-style)
    - [Markdown Formatting](#markdown-formatting)
    - [Alerts and Callouts](#alerts-and-callouts)
        - [New Content](#new-content)
- [Images](#images)
    - [Image Sources](#image-sources)
        - [OrcaSlicer Resources](#orcaslicer-resources)
        - [Wiki Images](#wiki-images)
            - [Image Naming](#image-naming)
            - [Image Placement](#image-placement)
            - [Linking Images](#linking-images)
                - [Examples](#examples)
    - [Avoid the Following](#avoid-the-following)
        - [Resize Images](#resize-images)
    - [Image Cropping and Highlighting](#image-cropping-and-highlighting)
    - [Recommended Formats](#recommended-formats)
- [Structuring Content](#structuring-content)
- [Commands and Code Blocks](#commands-and-code-blocks)
- [External Links](#external-links)

## Wiki Structure

Each page of the Wiki is a Markdown file located in the [OrcaSlicer_WIKI repository](https://github.com/OrcaSlicer/OrcaSlicer_WIKI).  
The wiki is organized into sections that cover different areas of the project.

### Home

The Home page is the starting point for the OrcaSlicer wiki. From there you can navigate to sections and topics related to the project.

When you create a new page or section, link it from the Home page under the appropriate category.  
The Home page currently organizes content in these top-level entries:

- ![printer](https://github.com/OrcaSlicer/OrcaSlicer/blob/main/resources/images/printer.svg?raw=true) [Printer Settings](home#printer-settings)
- ![filament](https://github.com/OrcaSlicer/OrcaSlicer/blob/main/resources/images/filament.svg?raw=true) [Material Settings](home#material-settings)
- ![process](https://github.com/OrcaSlicer/OrcaSlicer/blob/main/resources/images/process.svg?raw=true) [Process Settings](home#process-settings)
- ![tab_3d_active](https://github.com/OrcaSlicer/OrcaSlicer/blob/main/resources/images/tab_3d_active.svg?raw=true) [Prepare](home#prepare)
- ![tab_calibration_active](https://github.com/OrcaSlicer/OrcaSlicer/blob/main/resources/images/tab_calibration_active.svg?raw=true) [Calibrations](home#calibrations)
- ![im_code](https://github.com/OrcaSlicer/OrcaSlicer/blob/main/resources/images/im_code.svg?raw=true) [Developer Section](home#developer-section)

Each section can have multiple pages covering specific topics. For example, the [Process Settings](home#process-settings) section includes pages on [quality](home#quality-settings), [support](home#support-settings), and [others](home#others-settings).

#### Index and Navigation

GitHub Wiki uses file names as page identifiers. To link to a page, use the file name without the `.md` extension. If a file lives in a subdirectory, **do not include the subdirectory** in the link; link directly to the file name from the Home page.

For example, if you add `calibration/flow_ratio_calib.md`, link it like this:

```markdown
[Flow Ratio Calibration](flow_ratio_calib)
```

For long pages, include a table of contents at the top to help readers find sections quickly.

```markdown
- [Wiki Structure](#wiki-structure)
    - [Home](#home)
        - [Index and Navigation](#index-and-navigation)
    - [File Naming and Organization](#file-naming-and-organization)
- [Orca to Wiki Redirection](#orca-to-wiki-redirection)
- [Formatting and Style](#formatting-and-style)
    - [Markdown Formatting](#markdown-formatting)
    - [Alerts and Callouts](#alerts-and-callouts)
- [Images](#images)
    - [Image Sources](#image-sources)
        - [OrcaSlicer Resources](#orcaslicer-resources)
        - [Wiki Images](#wiki-images)
            - [Image Naming](#image-naming)
            - [Image Placement](#image-placement)
            - [Linking Images](#linking-images)
                - [Examples](#examples)
    - [Avoid the Following](#avoid-the-following)
        - [Resize Images](#resize-images)
    - [Image Cropping and Highlighting](#image-cropping-and-highlighting)
    - [Recommended Formats](#recommended-formats)
- [Structuring Content](#structuring-content)
- [Commands and Code Blocks](#commands-and-code-blocks)
- [External Links](#external-links)
```

> [!NOTE]
> If you're adding a new section, follow the existing structure and make sure it doesn't already fit an existing category. Link it from the Home page accordingly.

### File Naming and Organization

When creating new pages, follow these file-naming conventions:

- Use unique file names to avoid conflicts.
- Use descriptive names that reflect the page's content.
- Use snake_case for filenames (e.g.: `how_to_wiki.md`).
- If a page belongs to a section, include a suffix that clarifies it (for example, calibration pages should end with `-calib.md`, e.g. `flow_ratio_calib.md`).
- Place files in the appropriate subdirectory when applicable (e.g.: `calibration/` for calibration-related content).

## Orca to Wiki Redirection

OrcaSlicer can redirect users from the GUI to the appropriate wiki pages, making it easier to find relevant documentation.

The option-to-wiki mapping is defined in [src/slic3r/GUI/Tab.cpp](https://github.com/OrcaSlicer/OrcaSlicer/blob/main/src/slic3r/GUI/Tab.cpp).
The links naming uses the same format as the [Wiki Navigation described above](#index-and-navigation), `[filename]#[section(optional)]` e.g. `quality_settings_seam` or `quality_settings_seam#scarf-joint-seam`.

There are 3 main ways to set up these links:

1. Using `append_single_option_line` with a second string argument for the wiki page.  

    ```cpp
    optgroup->append_single_option_line("[OPTION_NAME]"); // Option without wiki page/redirection
    optgroup->append_single_option_line("[OPTION_NAME]", "[WIKI_LINK]"); // Option with wiki page and  redirection
    ```

     Example:

    ```cpp
    optgroup->append_single_option_line("seam_gap","quality_settings_seam"); // Wiki page and redirection
    optgroup->append_single_option_line("seam_slope_type", "quality_settings_seam#scarf-joint-seam"); // Wiki  page and redirection to `Scarf Joint Seam` section
    ```

2. Using `append_option_line` with a third string argument for the wiki page.

    ```cpp
    append_option_line([optgroup], [opt_key], "[WIKI_LINK]");
    ```

    Example:

    ```cpp
    append_option_line(optgroup, "machine_max_acceleration_x", "printer_motion_ability#acceleration-limitation");
    ```

3. Using grouped rows with `append_line` and setting the wiki target via `line.label_path`.

    ```cpp
    line.label_path = "[WIKI_LINK]";
    ```

    Example:

    ```cpp
    Line line = { L("Overhang speed"), L("...") };
    line.label_path = "speed_settings_overhang_speed#slow-down-for-overhang";
    line.append_option(optgroup->get_option("overhang_1_4_speed"));
    optgroup->append_line(line);
    ```

## Formatting and Style

Follow these style and formatting conventions when contributing to the wiki.

### Markdown Formatting

The wiki uses standard Markdown syntax for formatting and aims to maintain a consistent style across all pages. Avoid using raw HTML tags and prefer Markdown formatting instead.

Ensure your indentation is consistent, especially for code blocks and lists.

Refer to the [GitHub Markdown Guide](https://guides.github.com/features/mastering-markdown/) for more information on Markdown syntax.

### Alerts and Callouts

Use GitHub's alert syntax to add inline notes and warnings:

```markdown
> [!NOTE]
> Useful information that readers should know.

> [!TIP]
> Helpful advice for doing things more easily.

> [!IMPORTANT]
> Key information required to achieve a goal.

> [!WARNING]
> Urgent information to avoid problems.

> [!CAUTION]
> Warnings about risks or negative outcomes.
```

> [!NOTE]
> Refer to the [GitHub Alerts documentation](https://docs.github.com/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) for more details.

#### New Content

The Wiki should be updated to reflect the latest stable release with the addition of new features present in current nightly builds.  

When new features or upgrades are merged into the main branch, please add a note using the following format:

```markdown
> [!IMPORTANT]
> NEW FEATURE: **Feature short description**  
> Available in: [Nightly builds](https://github.com/OrcaSlicer/OrcaSlicer/releases/tag/nightly-builds) or Releases greater than **stable version number at merge time**.
```

Example:

> [!IMPORTANT]
> NEW FEATURE: **Inverse Hole Direction**  
> Available in: [Nightly builds](https://github.com/OrcaSlicer/OrcaSlicer/releases/tag/nightly-builds) or Releases greater than **2.3.2**.

This notes should be removed after a new stable release is made that includes the new feature.

## Images

Images are encouraged to enhance the clarity and quality of the wiki content. They help illustrate concepts, provide examples, and improve readability.

> [!CAUTION]
> Do not use images from third-party sources unless you have the proper permissions.

### Image Sources

#### OrcaSlicer Resources

Use images from the OrcaSlicer resources folder located at `\resources\images` in the OrcaSlicer repository. These images are designed to match the application's UI and maintain consistency.

#### Wiki Images

Use or add images in the `images/` directory of the [OrcaSlicer_WIKI repository](https://github.com/OrcaSlicer/OrcaSlicer_WIKI/tree/main/images).  
There you can find images already used in the wiki like screenshots, diagrams, and icons.

##### Image Naming

- Use clear, descriptive filenames that reflect the image content.
- For section-specific images, include the section name or initials (for example `pa-[description].png` for Pressure Advance images).

##### Image Placement

- General images should be placed in the `images/` directory.
- Section-specific images should be stored in their corresponding subdirectories (e.g., `images/calibration/` for calibration content).

> [!TIP]
> You can use `\resources\images` images used in the GUI.

##### Linking Images

Always use raw GitHub URLs for image links to ensure correct display:

Format = `![`filename`](` + Base URL + filename.extension + Raw tag + `)`

- Base URL:

  ```markdown
  https://github.com/OrcaSlicer/OrcaSlicer_WIKI/blob/main/images/
  ```

- Raw tag:

  ```markdown
  ?raw=true
  ```

###### Examples

- For an image in `images/` named `calibration.png`:

  ```markdown
  ![calibration](https://github.com/OrcaSlicer/OrcaSlicer_WIKI/blob/main/images/calibration.png?raw=true)
  ```

- For an image in a subdirectory like `images/GUI/combobox.png`:

  ```markdown
  ![combobox](https://github.com/OrcaSlicer/OrcaSlicer_WIKI/blob/main/images/GUI/combobox.png?raw=true)
  ```

> [!IMPORTANT]
> New or moved images may not appear in previews until the pull request is merged. Double-check paths and update links if you move files.

### Avoid the Following

- Relative paths
- GitHub Assets/user-content/user-images URLs
- External image links from temporary or unreliable hosts
- Images containing personal or sensitive information
- Using images for content that can be expressed in text, such as equations or code—use Markdown syntax or Mermaid/Math formatting instead.

> [!NOTE]
> When contributing section-specific images, follow the naming conventions and directory structure.

#### Resize Images

Avoid the resize of images and let the Wiki handle it automatically.

If resizing is necessary (e.g., for thumbnails), use the following syntax:

HTML Format = `<img alt="` + filename + `"` + `src="` + Base URL + filename.extension + Raw tag + size limit.
Example:

```html
<img alt="IS_damp_marlin_print_measure" src="https://github.com/OrcaSlicer/OrcaSlicer_WIKI/blob/main/images/InputShaping/IS_damp_marlin_print_measure.jpg?raw=true" height="200">
```

### Image Cropping and Highlighting

To ensure clarity:

- Crop images to focus on relevant areas.
- Use simple annotations (arrows, circles, rectangles) to highlight important parts without overloading the image.

### Recommended Formats

- **JPG:** Suitable for photographs. Avoid for images with text or fine detail due to compression artifacts.
- **PNG:** Ideal for screenshots or images with transparency. Ensure sufficient contrast for light and dark modes.
- **SVG:** Preferred when possible. SVGs support theme adaptation (light/dark mode), making them ideal for icons and diagrams.

## Structuring Content

Each page should have a clear objective. After a short introduction, choose a structure that fits the content:

- **Step-by-step guides:** Use for sequential procedures (for example calibration).
- **GUI-based reference:** Describe settings following OrcaSlicer's UI when sequence isn't required.

Example: explain **Layer Height** before **Initial Layer Height**, since the former is global and the latter only applies to the first layer.

## Commands and Code Blocks

When adding commands or code blocks please use the [Code Block with Syntax Highlighting feature of Markdown](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting).

- Use triple backticks (```) to enclose code blocks.
- Specify the language for proper highlighting and readability.

````markdown
```json
{
  "key": "value"
}
```
````

```json
{
  "key": "value"
}
```

## External Links

Be careful when linking to external resources.  
Ensure links are relevant and reliable and cite papers or articles when appropriate.