Editing the Documentation

This documentation is hosted on GitHub Pages and uses Jekyll with Markdown formatting.

Anyone can contribute improvements by submitting pull requests to the GitHub repository.

You are very much encouraged to help us improve this documentation.

Even small contributions can have a large impact and make lots of new user’s lives easier.

How to Contribute

In order to edit the documentation, you will need to:

Fork the repository on GitHub
Edit markdown files in the /docs folder
Submit a pull request with your changes

You can just write plain text, and it will be displayed, but there are ways to make it more useful using Markdown formatting.

It is fairly simple, and you can very easily just copy the way it is done on existing pages.

A good starting point is the GitHub Flavored Markdown documentation.

A few examples

Text

You can just write text and it will be displayed as-is.

To make sure lines are separated, leave an empty line between them, like this:

You can just write text and it will be displayed as-is.

To make sure lines are separated, leave an empty line between them, like this:

Headers

You can add headers to structure your page (like on this page), by doing:

## Header

The number of + signs determines how big the header is, the page title has one + sign, and the rest get more and more as they go deeper.

Links

To insert a link into a page, simply do:

This is a link: [link name](http://www.example.com).

Page links

To insert a link to a page on the wiki itself, do:

This is a link to the [Editing the wiki](editing-the-wiki) page.

Images

To insert an image, do:

{::nomarkdown}
<a href="/images/temporary/3d-printer-probe.jpg">
  <img src="/images/temporary/3d-printer-probe.jpg" alt="Sample Image"/>
</a>
{:/nomarkdown}

A nicer way of integrating images is to do the following:

<div class='panel panel-default wrap_right' style='width:450px;padding:10px '>
  <div class='panel-heading'><h4 class='panel-title'>A laser power supply</h4></div>
  <a href="/images/temporary/voltage-regulator-generic.jpg">
    <img src="/images/temporary/voltage-regulator-generic.jpg" style="width: 400px; height: 400px;"/>
  </a><br/>
  They use very high voltages and are dangerous
</div>

Which gives you a box, labels, and float control.

Note that you can change the floats to middle to make the image centered, or left to make it float to the left.

Commands

If you are mentioning a G-code, M-code, or configuration option, we have special tags for that. For G-codes and M-codes, use the <gcode> and <mcode> tags:

{::nomarkdown}
The <gcode>G1</gcode> G-code is pretty cool.
{:/nomarkdown}

Code

To insert code into the page, you can use the special code tag:

# This is redundant
Some code

It will be formatted as mono-space, and will not be interpreted as Wiki markup.

Alert Boxes

We use Shoelace alert components for notes, warnings, and other callouts:

Shiny box
With lots of yummy information

The syntax is:

<sl-alert variant="primary" open>
  <sl-icon slot="icon" name="lightbulb"></sl-icon>
  <strong>Shiny box</strong><br>
  With lots of yummy information
</sl-alert>

Available variants and their typical uses:

variant="danger": Red - for critical warnings
variant="warning": Orange - for important cautions
variant="primary": Blue - for tips and recommendations
variant="neutral": Gray - for general information and notes

Configuration Settings

For documenting Smoothieware configuration options, we have a special <setting> tag that creates interactive tooltips with detailed information:

Interactive Configuration Tags
The <setting> tag displays configuration options with rich tooltips showing defaults, valid values, and examples from our YAML configuration database.

Basic Syntax

For v1 settings:

<setting v1="alpha_steps_per_mm"></setting>

Which renders as:

For v2 settings:

<setting v2="actuator.alpha.steps_per_mm"></setting>

Which renders as:

For settings that exist in both versions:

<setting v1="acceleration" v2="motion control.default_acceleration"></setting>

Which renders as:

How It Works

When you use a <setting> tag:

It displays as an inline code element (monospace, highlighted)
Shows both v1 and v2 names when applicable
Provides an interactive tooltip on hover with:
- Full description
- Default values
- Valid value ranges
- Usage examples
- Related settings
All data comes from /docs/assets/data/smoothieware-v1-config.yaml

Examples

Here are some real-world examples:

Motor configuration:

Configure the <setting v1="alpha_steps_per_mm" v2="actuator.alpha.steps_per_mm"></setting>
setting to control how many motor steps equal 1mm of movement.

Renders as:

Configure the setting to control how many motor steps equal 1mm of movement.

Temperature control:

The hotend thermistor pin is set with
<setting v1="temperature_control.hotend.thermistor_pin" v2="thermistor_pin"></setting>.

Renders as:

The hotend thermistor pin is set with .

Motion settings:

Basic motion is controlled by <setting v1="acceleration" v2="motion control.default_acceleration"></setting>
and <setting v1="junction_deviation" v2="planner.junction_deviation"></setting>.

Renders as:

Basic motion is controlled by and .

Single version only:

The <setting v1="arm_solution"></setting> determines your kinematics type.

Renders as:

The determines your kinematics type.

Important Notes

Markdown Wrapper Required
When using setting tags inside regular markdown content, you must wrap them in {::nomarkdown}...{:/nomarkdown} blocks to prevent Jekyll from processing them as markdown.

Example with wrapper:

{::nomarkdown}
Configure your printer by setting <setting v1="alpha_steps_per_mm"></setting> first.
{:/nomarkdown}

Renders as:

Configure your printer by setting first.

Demo Attribute

For documentation pages (like this one), you can use the demo attribute to make custom tags render independently of the currently selected version:

<setting demo v1="alpha_steps_per_mm" v2="actuator.alpha.steps_per_mm"></setting>

With demo, the tag will always display both v1 and v2 content (for dual-attribute tags) regardless of the user’s version selector choice. This ensures documentation examples always look the same.

The demo attribute works with:

<setting> tags - always shows both versions
<versioned> tags - use demo="both" to always show both, demo="v1" for v1-only demo, demo="v2" for v2-only demo

Testing Your Settings

You can test setting tags and see all available examples on the Debug Settings page, which demonstrates various usage patterns and interactive features.

Raw Text Display

For displaying raw text, code snippets, or technical values in a monospace black box, we have the <raw> tag:

Simple Code Display
The <raw> tag displays text in a monospace black box with white text - perfect for inline code snippets, file paths, or technical values.

Basic Syntax

<raw>text content here</raw>

Which renders as: text content here

Use Cases

File paths:

The configuration file is located at <raw>/etc/smoothie/config</raw>.

Renders as:

The configuration file is located at /etc/smoothie/config.

Code snippets:

Use the command <mcode>M114</mcode> to query the current position.

Renders as:

Use the command M114 to query the current position.

Technical values:

Set the baud rate to <raw>115200</raw> for serial communication.

Renders as:

Set the baud rate to 115200 for serial communication.

Pin assignments:

Connect the signal wire to pin <raw>2.5</raw> on the board.

Renders as:

Connect the signal wire to pin 2.5 on the board.

Notes

The <raw> tag is simpler than the <setting> tag - it has no interactive features or tooltips
Best used for short inline code snippets or technical values
Text is displayed in white monospace font on a black background
Like other custom tags, wrap in {::nomarkdown}...{:/nomarkdown} when using in markdown content

G-code and M-code Display

For displaying G-codes and M-codes, we have specialized tags:

G-code and M-code Tags
Use <gcode> for G-codes and <mcode> for M-codes - same styling as <raw> but semantically correct.

Basic Syntax

For G-codes:

<gcode>G10</gcode>

Which renders as: G10

For M-codes:

<mcode>M119</mcode>

Which renders as: M119

Use Cases

G-code commands:

Use the <gcode>G28</gcode> command to home all axes.

Renders as:

Use the G28 command to home all axes.

M-code commands:

Send <mcode>M119</mcode> to check endstop status.

Renders as:

Send M119 to check endstop status.

In documentation:

The <gcode>G0</gcode> and <gcode>G1</gcode> commands control linear movement, while <mcode>M3</mcode> starts the spindle.

Renders as:

The G0 and G1 commands control linear movement, while M3 starts the spindle.

Pin Number Display

For displaying pin numbers and assignments with interactive tooltips, use the <pin> tag:

Interactive Pin Tag
The <pin> tag displays pin numbers with rich interactive tooltips showing pin capabilities, peripheral assignments, warnings, and configuration examples from our YAML pin database. Supports pin modifiers for showing configured behavior.

Basic Syntax

Simple pin number:

<pin>1.18</pin>

Which renders as: 1.18

Hover over the pin to see detailed information including:

Pin assignment and description
Hardware capabilities (PWM, ADC, interrupt support)
Peripheral connections
Alternate functions
Pin naming across different platforms (mBed, LPCXpresso)
Usage notes and warnings
Configuration examples

Pin Modifiers

The <pin> tag supports all Smoothieware pin modifiers. When you include modifiers, the popup will display an explanation of what each modifier does:

Pin with modifiers:

<pin>1.12o!</pin>

Which renders as: 1.12o!

Available modifiers:

! - Invert pin (reverses logic levels)
o - Open-drain mode (for shared signals)
^ - Pull-up enabled (default, weak pull to 3.3V)
v - Pull-down enabled (weak pull to ground)
- - No pull resistor (disables internal pulls)
@ - Repeater mode (maintains last state, rarely used)

Multiple modifiers:

You can combine multiple modifiers in any order:

<pin>2.11!o^</pin>

Which renders as: 2.11!o^

The popup will show each modifier with its meaning and usage information.

Common modifier combinations:

Endstop configured as <pin>1.24!^</pin> (inverted with pull-up)

Renders as:

Endstop configured as 1.24!^ (inverted with pull-up)

Shared alarm signal on <pin>2.11o^</pin> (open-drain with pull-up)

Renders as:

Shared alarm signal on 2.11o^ (open-drain with pull-up)

See the Pin Configuration page for detailed explanations of what each modifier does and when to use them.

Use Cases

Pin assignments:

Connect the thermistor to pin <pin>0.23</pin>.

Renders as:

Connect the thermistor to pin 0.23.

Wiring instructions:

The step signal goes to <pin>2.0</pin>, direction to <pin>0.5</pin>, and enable to <pin>0.4</pin>.

Renders as:

The step signal goes to 2.0, direction to 0.5, and enable to 0.4.

Hardware documentation:

Smoothieboard uses pins <pin>1.18</pin> through <pin>1.21</pin> for the X axis motor driver.

Renders as:

Smoothieboard uses pins 1.18 through 1.21 for the X axis motor driver.

Configuration examples with modifiers:

Configure your endstop as <pin>1.29!^</pin> for inverted logic with pull-up enabled.

Renders as:

Configure your endstop as 1.29!^ for inverted logic with pull-up enabled.

Version-Specific Content

For displaying content that differs between Smoothieware V1 and V2, we have the <versioned> tag system:

Version-Specific Content Display
The <versioned> tag lets you show different content for V1 and V2 users based on their version preference. Content can be displayed side-by-side (horizontal) or stacked (vertical).

Basic Syntax

The <versioned> tag contains two sections: <v1> for V1-specific content and <v2> for V2-specific content. To enable markdown processing inside these tags, wrap them with Kramdown’s {::nomarkdown} / {:/nomarkdown} directives:

{::nomarkdown}
<versioned>
<v1>
{:/nomarkdown}

V1 content here with **markdown** formatting.

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

V2 content here with **markdown** formatting.

{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

Horizontal Layout (Side-by-Side)

The default orientation is horizontal, which displays V1 and V2 content side-by-side (50/50 split). This is best for comparing similar content:

{::nomarkdown}
<versioned orientation="horizontal">
<v1>
{:/nomarkdown}

**V1 Configuration:**

- Setting A: `value1`
- Setting B: `value2`

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

**V2 Configuration:**

- Setting A: `new_value1`
- Setting B: `new_value2`

{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

You can omit orientation="horizontal" since it’s the default:

{::nomarkdown}
<versioned>
<v1>
{:/nomarkdown}

V1 content here.

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

V2 content here.

{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

Vertical Layout (Stacked)

For longer content sections, use vertical orientation to stack V1 and V2 content:

{::nomarkdown}
<versioned orientation="vertical">
<v1>
{:/nomarkdown}

**V1 Network Configuration:**

In Smoothieware V1, network settings use a flat structure:

- `network.enable true`
- `network.ip_address 192.168.1.100`
- `network.ip_mask 255.255.255.0`

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

**V2 Network Configuration:**

In Smoothieware V2, network settings use INI-style sections:

[network] enable = true ip_address = 192.168.1.100 netmask = 255.255.255.0


{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

Markdown Support

To use markdown inside versioned tags, you must wrap the HTML tags with {::nomarkdown} and {:/nomarkdown} directives. This tells Jekyll’s Kramdown processor to handle the content correctly.

Important rules:

Use {::nomarkdown} before opening HTML tags
Use {:/nomarkdown} after opening tags to re-enable markdown
Add blank lines after {:/nomarkdown} and before {::nomarkdown} for proper parsing
Repeat the pattern when closing tags

All markdown features work inside versioned content:

Bold and italic text
Bullet and numbered lists
Code blocks with triple backticks
Inline code
Tables
Links
Nested custom tags like <setting>, <pin>, <gcode>, etc.

Use Cases

Configuration comparisons:

{::nomarkdown}
<versioned>
<v1>
{:/nomarkdown}

Configure stepper motors with <setting v1="alpha_steps_per_mm"></setting>
and <setting v1="alpha_max_rate"></setting>.

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

Configure stepper motors with <setting v2="actuator.alpha.steps_per_mm"></setting>
and <setting v2="actuator.alpha.max_rate"></setting>.

{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

Renders as:

Configure stepper motors with and .

Feature availability:

{::nomarkdown}
<versioned orientation="vertical">
<v1>
{:/nomarkdown}

This feature is not available in V1.

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

**New in V2:**

This feature allows you to configure advanced motion control
with improved acceleration profiles.

{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

Renders as:

This feature is not available in V1.

New in V2:

This feature allows you to configure advanced motion control with improved acceleration profiles.

Pin assignments with differences:

{::nomarkdown}
<versioned>
<v1>
{:/nomarkdown}

Connect the thermistor to <pin>0.23</pin> and configure with
<setting v1="temperature_control.hotend.thermistor_pin"></setting>.

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

Connect the thermistor to <pin>0.23</pin> (same pin) and configure with
<setting v2="thermistor.hotend.pin"></setting>.

{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

Renders as:

Connect the thermistor to 0.23 and configure with

Connect the thermistor to 0.23 (same pin) and configure with

How It Works

The versioned tag system integrates with the version selector in the page header:

Show V1: Displays only V1 content (V2 hidden)
Show V2: Displays only V2 content (V1 hidden)
Show Both: Displays both side-by-side or stacked with color-coded borders
- V1 content: orange dotted border
- V2 content: blue dotted border

When showing only one version, the content appears as normal page text with no special styling. When showing both, the borders help distinguish between versions.

Users can click on the V1/V2 labels to open the version selector and switch between modes.

Important Notes

Kramdown Wrappers Required for Markdown
Without the {::nomarkdown} / {:/nomarkdown} wrappers, markdown inside versioned tags will NOT be processed. Always use the wrapper pattern shown in the examples above.

Test Your Versioned Content
See the Debug Versioned Tags page for comprehensive examples and to test how versioned content appears in different modes.

Review Tags (For AI-Assisted Updates)

The <review> tag is used during AI-assisted documentation updates to propose changes that require human review before being finalized.

Review Workflow for Documentation Updates
The <review> tag enables a structured workflow where AI agents can propose documentation changes, and human reviewers can accept, reject, or comment on each change individually before finalizing.

Combining Review and Versioned Tags

The <review> and <versioned> tags can be combined to propose version-specific content changes. Here’s a working example from the community page:

{::nomarkdown}
<review id="page-name:section-description">
<proposal>
{:/nomarkdown}

Introductory text that applies to both versions.

{::nomarkdown}
<versioned orientation="vertical">
<v1>
{:/nomarkdown}

**V1-specific content:**

- List item with <setting v1="some_setting"></setting>
- Another item

<sl-alert variant="primary" open>
  <sl-icon slot="icon" name="info-circle"></sl-icon>
  V1-specific alert or note
</sl-alert>

{::nomarkdown}
</v1>
<v2>
{:/nomarkdown}

**V2-specific content:**

- Different list for V2
- With different settings

<sl-alert variant="primary" open>
  <sl-icon slot="icon" name="info-circle"></sl-icon>
  V2-specific alert or note
</sl-alert>

{::nomarkdown}
</v2>
</versioned>
{:/nomarkdown}

{::nomarkdown}
</proposal>
<original>
{:/nomarkdown}

Original content that's being replaced.

{::nomarkdown}
</original>
</review>
{:/nomarkdown}

Key points when combining these tags:

Review wraps versioned: The <review> tag is the outermost wrapper
Versioned inside proposal: Place the <versioned> tag inside the <proposal> section
Proper nesting: Each tag pair must have correct {::nomarkdown} / {:/nomarkdown} wrappers
Blank lines: Add blank lines after {:/nomarkdown} and before {::nomarkdown} for proper markdown parsing
Custom tags work: You can use <setting>, <pin>, Shoelace components, etc. inside versioned sections

Tag Structure

{::nomarkdown}
<review id="page-name:change-description">
<proposal>
{:/nomarkdown}

New or updated content goes here. Can include markdown, <setting> tags, <pin> tags, etc.

{::nomarkdown}
</proposal>
<original>
{:/nomarkdown}

Original content being replaced (optional - omit if adding new content)

{::nomarkdown}
</original>
</review>
{:/nomarkdown}

Review ID Format

The id attribute must follow the format: page-name:brief-description

Examples:

extruders:pin-descriptions
motion-control:acceleration-formula
3d-printer-guide:wiring-section

Tag Behavior

On Localhost (http://localhost:4000):

Shows proposed content with pink background
Displays control icons in top-right:
- Toggle: Switch between proposal and original
- Accept (green checkmark): Mark change as accepted
- Reject (red X): Mark change as rejected
- Comment (blue chat): Add review notes
All actions saved to browser localStorage
Console logs review data for export

On Production Site (smoothieware.org):

Shows only original content (or nothing if no original)
No backgrounds, no icons
Completely invisible to end users

Using Markdown Inside Review Tags

Both <proposal> and <original> tags support markdown, but you must use Kramdown’s {::nomarkdown} directives (same as <versioned> tag):

{::nomarkdown}
<review id="example:markdown-demo">
<proposal>
{:/nomarkdown}

The **acceleration** setting controls how quickly the machine speeds up.

You can set it using:
<setting v1="acceleration" v2="motion control.default_acceleration"></setting>

For more info, see the [motion control guide](/motion-control).

{::nomarkdown}
</proposal>
<original>
{:/nomarkdown}

The acceleration setting controls speed.

{::nomarkdown}
</original>
</review>
{:/nomarkdown}

Critical Requirements:

Must wrap with {::nomarkdown} / {:/nomarkdown} to enable markdown processing
Place {:/nomarkdown} immediately after opening tags (<proposal>, <original>)
Place {::nomarkdown} immediately before closing tags (</proposal>, </original>)
Custom tags (<setting>, <pin>, etc.) work normally inside review content
Blank lines create paragraph breaks
Use standard markdown syntax between the directives

Workflow for AI Updates

AI proposes changes: Wraps updates in <review> tags with unique IDs
Human reviews: Views changes on localhost, uses icons to accept/reject/comment
Export review data: Copy JSON from browser console
AI processes feedback: Accepts accepted changes, refines commented changes, removes rejected changes
Finalize: Remove <review> tags, leaving only final content

Review Data Export

All review actions are logged to the browser console:

{
    "extruders:pin-descriptions": {
        "accept": true
    },
    "extruders:safety-warning": {
        "comment": true,
        "note": "Add metric example"
    },
    "motion-control:formula": {
        "reject": true
    }
}

Copy this JSON to provide feedback to the AI agent for refinement.

Best Practices

Unique IDs: Each review tag must have a globally unique ID
Descriptive IDs: Use format page:section for clarity
One change per tag: Keep proposals focused and atomic
Include original: Always include <original> content when replacing (not adding)
Test rendering: Verify custom tags render correctly inside reviews
Clean up: Remove all <review> tags before pushing to production

Production Safety
Review tags should NEVER be pushed to the production site. They are for localhost testing only. On production, they automatically show only the original content with no visual indicators.

Test Review Tags
See the Debug Review Tags page for interactive examples and to test the review workflow.

Lists

You can make nicely formatted lists by doing:

- Item one
- Item two
- Item three

They then look like this:

Item one
Item two
Item three

HTML

You can insert raw HTML into the page by doing:

<h1>Custom HTML</h1>
<p>Something else</p>
{::nomarkdown}
<a href="/images/circuit.png">
  <img src="/images/circuit.png" alt="hello ;-)"/>
</a>
{:/nomarkdown}

This is in particular useful to insert Youtube videos and the like.

Page Layout

The site uses Jekyll with custom CSS for formatting.

For images, you can float them to the right or center them:

Floating an image to the right:

{::nomarkdown}
<a href="/images/temporary/pick-place-machine-generic.jpg">
  <img src="/images/temporary/pick-place-machine-generic.jpg" alt="Description" style="width: 200px; height: 150px; float: right; margin-left: 1rem;"/>
</a>
{:/nomarkdown}

Centering a large image:

{::nomarkdown}
<div style="text-align: center;">
  <a href="/images/temporary/pick-place-machine-generic.jpg">
    <img src="/images/temporary/pick-place-machine-generic.jpg" alt="Description" style="min-width: 640px; width: 100%; max-width: 800px;"/>
  </a>
</div>
{:/nomarkdown}

This is a wiki! If you'd like to improve this page, you can edit it on GitHub.