MarlinDocumentation: the Jekyll source behind marlinfw.org

What MarlinDocumentation is, and what it is not

The README opens by stating that this repository contains the raw documentation for Marlin 3D printer firmware, which is automatically deployed to marlinfw.org. That single sentence settles the scope. This is the source of the website, not the firmware. If you arrived looking for Marlin configuration, a download of the firmware itself, or an Ender 3 setup guide, you are in the wrong repository; the README points to MarlinFirmware/Marlin for the firmware and the site itself is the published output.

The audience is narrower than the firmware's. It is for people who want to complete, correct, or create articles, because the README says the documentation is open and available on GitHub so anyone may contribute. Practically, that means technical writers, maintainers of specific firmware features, and users who found an error on marlinfw.org and want it fixed at the source rather than reported into the void.

The repository layout reflects that job. The top level holds content directories such as _basics, _configuration, _development, _features, _gcode, _hardware, _setting, and _tools, alongside _layouts, _includes, _sass, _plugins, and _data. The README also mentions a _tmp folder for work in progress, which it says will not be included in the site deployment. That is a useful escape hatch: drafts can live in the repository without appearing on marlinfw.org.

How the Jekyll build and deployment path works

The README lists the stack plainly: Ruby, RubyGems, Jekyll, and GitHub Pages. Content is Markdown, and the README describes the format as Markdown in a YAML wrapper. That wrapper is the part that bites. Each page carries YAML front matter, and the README warns that even small typos can cause Jekyll to reject the page. A stray colon or an unclosed quote in the header does not degrade the page; it stops the build.

The data flow is one direction. You fork the repository, clone your fork, branch from master, add or edit a Markdown file, commit, push to your fork, and open a pull request to the upstream master branch. The README is explicit that all work should happen in your own fork before being submitted as a pull request. Deployment is not something a contributor triggers. The README says the documentation is automatically deployed to marlinfw.org, and the repository carries a GitHub Actions workflow at .github/workflows/jekyll-pub.yml, which is the visible automation behind that sentence.

The repository also ships a Gemfile and a .ruby-version file at the top level. The Gemfile is what Bundler reads to install the Jekyll toolchain, and .ruby-version pins the interpreter version the project expects. Neither file is described in the README text, but their presence tells you the intended workflow is a local Bundler install rather than a globally installed Jekyll gem.

Installing Ruby and previewing the docs locally

The README devotes a full section to a local Jekyll preview and gives separate instructions per platform. On Windows it points to Ruby+Devkit 3.3.4 from the RubyInstaller Download Archives, installed with default options, followed by the ridk install step in the last stage of the wizard, where you choose option 3 for the MSYS2 and MINGW development tool chain. The README explains why: that toolchain is needed for installing gems with native extensions.

After installation, open a new Command Prompt so PATH changes take effect and confirm the interpreter:

ruby -v

The README says that if you see ruby 3.3.4 (2024-07-09 revision be1089c8ec) reported, you can proceed to the project setup. On macOS the README notes that system Ruby may be preinstalled but is outdated and not recommended for general use, and it covers installation through Homebrew or MacPorts. On Ubuntu it gives its own instructions. Those two platform sections are truncated in the README, so the exact commands for macOS and Ubuntu are not reproduced here; read them in the repository before starting.

The contribution loop itself is spelled out with concrete commands. Change into the root of C:\, then clone the repository:

cd C:\
git clone https://github.com/MarlinFirmware/MarlinDocumentation.git

The README says this creates a local C:\MarlinDocumentation folder linked to your fork. Branch from master before you touch anything, naming the branch after the topic:

git checkout master -b doc-mashed_potatoes

New documents go inside the _docs folder. The README's example is a new file named mashed-potatoes.md. When it is ready, the command-line sequence is:

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

Then open a pull request against MarlinFirmware/MarlinDocumentation. What you should see after the push is your branch on your own fork, not on upstream, which is the point of the fork-first workflow.

Editorial rules you have to follow, and the _tmp escape hatch

The README's editorial style section is short but binding. It asks contributors to be neutral, concise, and straightforward, to avoid personal pronouns unless avoiding them proves awkward, to provide images and examples where needed, and to check spelling, grammar, and punctuation. There is also a coding style section that repeats the YAML warning and points to the local Jekyll build as the way to find your errors.

Two things stand out. First, the style guidance is about tone, not structure, so it will not tell you where a new page belongs among _basics, _configuration, _features, _gcode, or _hardware. You have to infer that from the existing tree. Second, the README does not document rollback or how to revert a deployed page. If a bad edit reaches marlinfw.org, the recovery path is a normal git revert through a pull request, but the README is silent on it, so do not expect a documented undo procedure.

The _tmp folder is the one concession to unfinished work. The README states that files placed there will not be included in the site deployment. That makes it the right place for a half-written page that you want in version control without publishing. It is not a review queue and nothing in the README suggests it is monitored.

Where this repository is the wrong tool

The most common mismatch is intent. Someone searching for Marlin firmware, Marlin configuration, or a Marlin download for an Ender 3 wants firmware and configuration guidance, and this repository cannot give them the binary or the board setup. The README itself redirects to the Marlin firmware repository. Cloning MarlinDocumentation and expecting to build firmware will end in confusion, because the top level is Jekyll content and site assets, not C++ sources.

A second mismatch is the toolchain. Contributing here means installing Ruby and Jekyll and getting native gem extensions to compile, which on Windows requires the MSYS2 and MINGW development tool chain. If your goal is to fix a typo on one page and you have no Ruby environment, the setup cost is real. The GitHub web interface can create a branch and a commit without any local install, but the README does not walk through that path, and you lose the local preview that the README recommends for catching YAML errors before they reach the build.

A third limit is scope of review. The README describes the contribution process and the style expectations, and nothing more. It does not describe a review timeline, an approval policy, or what happens to a pull request that changes an existing article's meaning. Treat it as a documentation repository maintained by volunteers, not a service with a response guarantee.

MarlinDocumentation compared with writing on the Marlin wiki

The obvious alternative for someone who just wants to document a Marlin feature is a wiki, where a page can be edited in the browser and saved immediately. The difference in approach is the build. A wiki stores rendered pages and edits them in place. MarlinDocumentation stores Markdown with YAML front matter, feeds it through Jekyll, and deploys the result to marlinfw.org. That extra layer is what makes the README warn about typos breaking the page, and it is also what makes the output consistent: shared _layouts, _includes, and _sass apply to every article, and navigation is generated rather than hand-maintained.

The trade is latency for structure. A wiki edit is live in seconds but drifts in formatting across pages. A pull request here goes through a fork, a branch, and a review before it appears on the site, and in return the page inherits the site's templates and the deployment pipeline in .github/workflows/jekyll-pub.yml. If you want to publish a correction today with no local environment, a wiki-style flow is faster. If the correction needs to sit alongside the rest of the Marlin documentation under one consistent layout, this repository is the right place.

Licence and the cost of keeping a fork current

The repository carries the GPL-3.0 licence, and the README's table of contents ends with a License entry. Because the site content is documentation rather than program code, the practical consequence for a contributor is that your submitted text becomes part of a GPL-3.0 licensed repository. If your employer or your own project has rules about which licences your writing can be published under, check that before you open a pull request. This is a description of the licence file present in the repository, not legal advice, and it does not settle how documentation and code are treated together.

On maintenance cost, there is no last push date available, so there is no basis for calling the repository actively maintained or otherwise. What can be said is structural: the README pins Ruby+Devkit 3.3.4 for Windows, and the repository includes a .ruby-version file, so the interpreter version is a moving target you will need to match when the project updates it. Upgrading means reinstalling or switching Ruby, reinstalling gems through Bundler from the Gemfile, and rebuilding the Jekyll site to confirm nothing in the layouts or plugins broke. Budget for that whenever the pinned version changes, and expect the YAML front matter to be the first thing that fails if it does.

Editorial conclusion

Adopt it if you write or correct Marlin documentation and are willing to run a Jekyll preview before opening a pull request against master. Do not adopt it if you want to configure firmware, install Marlin, or compile a board; that lives in MarlinFirmware/Marlin, not here. Before your first commit, verify Ruby 3.3.4 responds to ruby -v, confirm your fork is the remote you push to, and check that your new file sits under _docs with valid YAML front matter, since the README warns that small typos make Jekyll reject the page.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository