MarlinFirmware/MarlinDocumentation

Marlin Documentation Project

About

This repository contains the raw documentation for Marlin 3D printer firmware which is automatically deployed to marlinfw.org. This documentation is open and available on GitHub so anyone may contribute by completing, correcting, or creating articles.

Table of Contents

• Technical details
• How to contribute
  • Coding style
  • Editorial style
  • Work in progress
• Local Jekyll preview
  • Installing Ruby on Windows
  • Installing Ruby on macOS
  • Installing Ruby on Ubuntu
  • Set up Marlin Documentation project
  • Jekyll basics
  • Previewing content
  • License

Technical details

The Marlin Documentation Project is built using the following technologies:

• Ruby
• RubyGems
• Jekyll
• GitHub Pages

How to contribute

To work with the documentation, first fork this repository to your GitHub account, then clone your MarlinDocumentation fork locally. You should do all work within your own fork before submitting it as a Pull Request to the master branch. You can download the GitHub Desktop app and use GitHub's "Open in Desktop" option, or from your own desktop, open a terminal/cmd window and do:

For example, change into the root of C:\:

cd C:\

Clone Marlin Documentation repository:

git clone https://github.com/MarlinFirmware/MarlinDocumentation.git

This will create a local C:\MarlinDocumentation folder linked to your fork.

To add new documentation or edit existing documentation, start by creating a new branch as a copy of the master branch. You can do this using the GitHub web interface, from within GitHub Desktop, or from the command line.

If your new document is about "mashed potatoes" then name the new branch accordingly:

git checkout master -b doc-mashed_potatoes

Inside the _docs folder, add the new file mashed-potatoes.md and let flow all your creativity into it. When you feel your masterpiece is ready to be shared with the world, commit the changes and push them up to your Marlin Documentation fork. This is done most easily from within the GitHub Desktop app, but here are the command line commands for reference:

git add mashed-potatoes.md
git commit -m "Added a new document about potatoes"
git push

Next, start a new Pull Request to the upstream repository (MarlinFirmware/MarlinDocumentation).

[!TIP] Check out GitHub's documentation on creating a new branch, managing branches, and creating Pull Requests if you're new to contributing with git.

Coding style

This Jekyll-based site is based on the Markdown language in delicious YAML wrapper. Be careful with this format because even small typos can cause Jekyll to reject the page. If you've installed Jekyll as described below, you can use it to build and preview the documentation and this will tell you where your errors are.

Editorial style

Try to be neutral, concise, and straightforward. Avoid use of personal pronouns, unless avoiding them proves awkward. Provide images and give examples where needed. Check your spelling, grammar, and punctuation.

Work in progress

You can use the _tmp folder for work-in-progress, and they will not be included in the site deployment.

Local Jekyll preview

If you'd like to be able to preview your contributions before submitting them, you'll need to install Jekyll on your system. Instructions for Windows and macOS are given below:

Installing Ruby on Windows

1. Download and install a Ruby+Devkit 3.3.4 from RubyInstaller Download Archives. Use default options for installation.

2. Run the ridk install step on the last stage of the installation wizard. Choose option 3 for MSYS2 and MINGW development tool chain. This is needed for installing gems with native extensions. You can find additional information regarding this in the RubyInstaller Documentation.

[!TIP] Once the MSYS2 and MINGW development toolchain install is complete, the installation wizard will reprompt which components should be installed. If you see a "Install MSYS2 and MINGW development toolchain succeeded" message above it, you can close the Command Prompt window and continue below.

3. Open a new Command Prompt so that changes to the PATH environment variable become effective, then check that everything is working:

   ruby -v
   

   If ruby 3.3.4 (2024-07-09 revision be1089c8ec) is reported, then proceed to Set up the Marlin Documentation project.

Installing Ruby on macOS

[!NOTE] Ruby may come preinstalled, but macOS' "system Ruby" is outdated, unmaintained, and not recommended for general use.

There are many popular package managers for macOS, but we'll cover installation with Homebrew & MacPorts.

1. Install a package manager. You do not need to install both:

   • Install Homebrew by launching Terminal and running the following command:

     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
     

   • Install MacPorts by downloading & installing the correct package for your version of macOS from the Installing MacPorts page.

     • Either Xcode or Command Line Tools for Xcode are required to install packages with MacPorts. You do not need to install both. These are available for free on Apple's Developer Program website. An Apple Developer Program membership is not required, but you will need to sign in with your Apple ID.

2. Install chruby and ruby-install:

   • Homebrew:

     brew install chruby ruby-install
     

   • MacPorts:

     sudo port install chruby ruby-install
     

3. Install Ruby 3.3.4:

   ruby-install ruby 3.3.4
   

   The configure, build, and install process will take a few minutes.

4. Configure your shell to automatically use chruby:

   • Homebrew:

     echo "" >> ~/.zshrc
     echo "# Ruby Configuration" >> ~/.zshrc
     echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
     echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
     echo "chruby ruby-3.3.4" >> ~/.zshrc
     

   • MacPorts:

     echo "" >> ~/.zshrc
     echo "# Ruby Configuration" >> ~/.zshrc
     echo "source ${prefix}/opt/local/share/chruby/chruby.sh" >> ~/.zshrc
     echo "source ${prefix}/opt/local/share/chruby/auto.sh" >> ~/.zshrc
     echo "chruby ruby-3.3.4" >> ~/.zshrc
     

5. Quit and relaunch Terminal, then check that everything is working:

   ruby -v
   

   It should report ruby 3.3.4 (2024-07-09 revision be1089c8ec). If not, repeat the above steps.

[!NOTE] When using ruby-install you'll find your Ruby installations in ~/.rubies/ and you can switch between them with chruby. New instances of zsh in Terminal will default to 3.3.4 due to the changes made to ~/.zshrc.

6. Proceed to Set up the Marlin Documentation project. (Note that bundler is already included.)

Installing Ruby on Ubuntu

1. Ensure APT is up to date:

   sudo apt update
   

2. Install prerequisites:

   sudo apt install git curl libssl-dev libreadline-dev zlib1g-dev autoconf bison build-essential libyaml-dev libreadline-dev libncurses5-dev libffi-dev libgdbm-dev
   

3. Install rbenv:

   curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
   echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
   echo 'eval "$(rbenv init -)"' >> ~/.bashrc
   source ~/.bashrc
   

4. Install Ruby 3.3.4:

   rbenv install 3.3.4
   rbenv global 3.3.4
   

[!NOTE] When using rbenv you'll find your Ruby installations in ~/.rbenv/versions/ and you can switch between them with rbenv global <version>.

5. Check Ruby version:

   ruby -v
   

   It should report ruby 3.3.4 (2024-07-09 revision be1089c8ec). If not, repeat the above steps.

6. Add environment variables to your ~/.bashrc file to configure the gem installation path:

   echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
   echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
   echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

7. Install Bundler Gem:

   gem install bundler
   

8. Proceed to Set up Marlin Documentation project.

Set up Marlin Documentation project

Once Ruby is installed, set up the Marlin Documentation project with Bundler. Open Command Prompt or Terminal and cd to the working path of your Marlin Documentation fork. Execute the following commands:

rm -f Gemfile.lock
bundle config set path 'vendor/bundle'
bundle install

[!NOTE] You only need to execute the above commands once to complete the install. If you see errors at this stage you may need to update your Ruby installation, fix your Ruby environment, or resolve dependencies between the Ruby gems.

Jekyll basics

Jekyll uses a combination of YAML, Markdown, Liquid, and HTML to define the site content and layout. A _config.yml file defines a site structure with "collections" corresponding to sub-folders. The website is "compiled" to produce static HTML and Javascript. The most important folders in the site are:

• _layouts contains the general layouts (aka page templates).
• _includes has partial layouts included by others.
• _meta is where we keep top-level page descriptions.
• Sections: _basics, _configuration, _development, _features, _gcode, _hardware….

Previewing content

To start a mini web server and preview your changes, run the following command:

bundle exec jekyll serve --watch --incremental

With the serve --watch --incremental parameters, Jekyll watches local files for changes and triggers an automatic incremental build of the site on every save. It also starts a mini-web server so documentation can be previewed in a browser at http://localhost:4000/.

[!TIP] The main Marlin repository comes with the mfdoc script containing the commands above as a shortcut to preview the documentation.

License

This documentation is licensed under the GPLv3 license.