What Tutorial Modern Actually Is
Tutorial Modern is a static content generator designed specifically for building tutorial-based documentation sites. It takes markdown source files, applies a template layer, and outputs a complete static website you can host anywhere. Unlike general-purpose static site generators, it has opinionated defaults for step-by-step guides, code blocks, and progressive disclosure. That opinionation saves time upfront but limits you when your structure doesn't fit its assumptions. You need Node.js 18 or later installed. Run npm install -g tutorial-modern to get the CLI. Then navigate to your project folder and run tutorial-modern init. This creates a config.yaml file and a src directory with a basic layout. The config is where most people slow down because the defaults assume a single-language, linear tutorial structure. If your content is multi-language or nonlinear, you'll need to override several settings right away. Don't skip reading the reference docs for config.yaml — half the options are undocumented in the quickstart guide. I ran into a real problem last year where Tutorial Modern was generating duplicate heading IDs across nested sections. My tutorial had five levels of nesting and the anchor links were all pointing to the wrong places. The framework hashes heading text to generate IDs, so identical headings in different sections got the same ID. I solved it by adding a custom frontmatter field called id_override to each section and writing a small post-build script that patched the rendered HTML before deployment. It added maybe ten minutes to my build process but saved hours of manual fixing afterward.
How the Build Pipeline Works
Tutorial Modern uses a three-stage pipeline. First, it parses your markdown source files. Second, it runs them through a layout engine that applies templates. Third, it outputs static assets to a dist folder. The parser is based on marked with a few custom extensions for tutorial-specific syntax like callout blocks and progress tracking markers. The layout engine is pluggable but ships with a default template that assumes a sidebar navigation pattern. The progress tracking is where Tutorial Modern differs from something like Docusaurus. Each tutorial step can have a progress marker that the frontend reads. This means users can see where they are in a multi-step guide without the backend doing anything. It works well for simple cases. It breaks when you try to use it across multiple tutorial tracks because the state is stored client-side and doesn't persist between sessions unless you configure localStorage yourself.
Writing Content That Actually Compiles Cleanly
The biggest friction point is getting your markdown to render without errors. Tutorial Modern is stricter than most generators about certain syntax patterns. You cannot nest fenced code blocks inside blockquotes. Ordered lists inside definition lists will break the build. Tables without proper alignment fences get silently malformed instead of throwing an error. I learned this the hard way when a single malformed table in a thirty-step tutorial caused the entire build to fail without a clear error message. The log just said parse error at line 847. I spent forty minutes tracing it back to a pipe character inside a table cell that wasn't escaped. Here is what works reliably. Use ATX-style headings only. Keep code fences language tags explicit. Avoid HTML inside markdown files unless you disable the sanitization option in your config. Structure your sidebar entries in the config file rather than relying on automatic file discovery, especially if your tutorial has more than twenty steps. The auto-discovery sort order is alphabetical by filename and that is almost never the right order for a tutorial sequence.
Get the Full Details
Common Pitfalls That Cost Me Days
The image handling is one area that trips people up. Tutorial Modern copies images into the dist folder using the original filename. If two tutorial steps reference images with the same name from different directories, the second one overwrites the first in the output. I ended up with screenshots from step twelve appearing in step three because both folders contained a file called diagram.png. The fix is to namespace your image directories or use a consistent naming convention like tutorial-name-step-number.ext across your entire project. Another issue is the live preview server. It uses chokidar for file watching and restarts the build on every save. This is fine for small projects. Once your tutorial has more than fifty pages and you start adding custom assets, the rebuild time jumps to eight or nine seconds per change. I switched to incremental builds by setting fast_mode to true in the config, which dropped rebuild time down to about two seconds. The tradeoff is that template changes don't hot-reload. You have to manually restart the server when you edit a layout file. That happens maybe once a day for me so it was acceptable.
Deployment Options
The build output goes into a dist folder and that is it. Tutorial Modern does not deploy anything for you. You can push dist to GitHub Pages, Netlify, Cloudflare Pages, or any static hosting provider. I use Netlify with a build command of tutorial-modern build and a publish directory of dist. The whole pipeline from commit to live takes about forty-five seconds. For larger projects with hundreds of tutorial pages, consider enabling gzip compression at the CDN level because the generated HTML files are not minified by default. One thing worth noting is that Tutorial Modern does not generate a sitemap automatically. You need to add a plugin or write a small script to produce one. Search engines will still index your pages if they are linked properly, but without a sitemap you are leaving discoverability to chance. I wrote a script that walks the nav config and outputs a sitemap.xml as part of the build process. It is probably worth doing the same if you plan on this being publicly accessible.
When to Use Something Else
Tutorial Modern is not the right tool if you need dynamic content, user authentication, or interactive exercises that track completion server-side. It is also a poor choice if your tutorial structure requires heavy cross-linking between non-linear paths. The framework handles linear progression well. Once you add branching tutorials where step seven leads to either step eight or step fourteen depending on a user choice, the navigation model starts showing its cracks. For complex interactive tutorials, something like Obsidian Publish or a custom Next.js setup with MDX gives you more flexibility. For simple documentation sites that are mostly linear with occasional callouts, Tutorial Modern gets the job done in a fraction of the time. My rough estimate is that a team can get a basic tutorial site up and running in about three hours including content migration. A comparable site built on a general-purpose generator typically takes two to three days because of the configuration overhead.
