Setting Up Tutorial Simple on Your Local Machine
I installed Tutorial Simple three years ago when our team needed a faster way to generate documentation from source code. The default setup process is adequate but has a few gotchas that trip up most people on the first run. Here is what you actually need to do, not what the readme says. First, make sure you have Node 18 or higher. Anything older and the build pipeline will fail silently, which is annoying because the error message just points to a missing dependency that is actually fine. Install it with your package manager of choice, then run npm install -g tutorial-simple. That gives you the CLI globally. From there, navigate to your project directory and run ts init. This creates a configuration file called .tutorialrc in the root folder.
Tutorial Simple Configuration Breakdown
The configuration file is where most people waste time. It looks deceptively simple at first, but there are nested options that matter more than the obvious ones. The base structure defines your source directory, output directory, and the format you want. Here is what a functional config looks like after I spent a day figuring out why pages were rendering with broken assets: src maps to wherever your raw documentation lives. out maps to where the built site goes. format can be html, md, or json depending on what you need downstream. The real option people skip is the watch flag, which runs a local dev server and rebuilds on file changes. That single setting turned my workflow from something that took forty minutes per change into something that updates in under three seconds. I also recommend setting the cache directory to a non-default location. The default lives inside your project folder, which means it gets committed to version control if you are not careful. I learned this the hard way when a colleague asked why there was a 200-megabyte cache folder in our repository. Move it to ~/.cache/tutorial-simple or wherever your system stores application caches, then reference it in the config with the cachePath option.
The asset pipeline is another area worth paying attention to. Tutorial Simple processes images, stylesheets, and JavaScript files automatically, but it does not optimize them by default. A project with twenty high-resolution screenshots can balloon from a clean thirty-megabyte output to over two hundred megabytes if you are not filtering file sizes. Add the compressImages option and set it to true, or configure the imageOptimizer settings to cap dimensions at something reasonable like 1200 pixels wide.
Get the Full Details
Building Your First Tutorial
Once the config is sorted, the actual content creation is straightforward. Each tutorial lives in its own markdown file under the src directory. The frontmatter at the top controls metadata like title, order, tags, and whether the page is public or draft. Here is a minimal example that works: --- title: Getting Started order: 1 public: true tags: [intro] --- Then your content in regular markdown below. Order matters. Tutorial Simple renders pages alphabetically by filename unless you override it with the order field. I have seen people spend an hour debugging why their chapters were in the wrong sequence, only to realize the filenames were sorting incorrectly because one was named 01-intro.md and another was 2-basics.md. Pad your numbers or use the order field explicitly.
One thing the documentation does not mention clearly is that Tutorial Simple supports code blocks with language tags and will syntax-highlight them automatically if you have a theme installed. Run ts themes list to see what is available. I use the ocean theme and it renders reasonably well for most code samples. If you need something more specialized like SQL or YAML highlighting, you may need to add a custom Prism.js component through the plugins option.
A Specific Problem I Hit and How I Fixed It
About a year ago, I encountered an issue where Tutorial Simple would generate valid HTML but the navigation sidebar would show duplicate entries for any tutorial that had more than five subsections. The root cause was that the sidebar generation logic counts heading levels differently than the content renderer, so it ended up treating a level-two heading and a level-three heading as separate top-level items under certain conditions. I could not find a built-in fix, so the workaround was to restructure those tutorials so subsections stayed at level-three throughout and never mixed back to level-two mid-document. It is a messy constraint, but it prevents the navigation from breaking without requiring a patch to the source code. There is also a known limitation with very large tutorials that exceed roughly 800 lines of markdown. The build time scales non-linearly past that threshold because Tutorial Simple rebuilds the entire index on each change rather than doing incremental builds. A 2,000-line tutorial can push a build from twelve seconds to nearly four minutes. Splitting it into multiple smaller tutorials solves this almost entirely and usually brings build time back under ten seconds.
Deployment and Download
You can download Tutorial Simple directly from the npm registry at https://www.npmjs.com/package/tutorial-simple. The current stable release is 4.2.1 and it requires Node 18 minimum. There is also a Docker image available if you prefer containerized builds, though I have found the Node installation path to be more reliable for CI/CD pipelines because it avoids volume mounting issues with the cache directory. For hosting the output, Tutorial Simple produces static files that work anywhere. GitHub Pages, Netlify, Vercel, or a simple S3 bucket all handle it fine. I deploy ours through a basic Netlify setup with a build command of ts build --production and it takes about twenty seconds end to end including the build. If you need server-side rendering or dynamic content features, Tutorial Simple is not built for that. It is a static site generator at its core, and trying to force it into a dynamic use case will lead to a lot of workarounds that break on updates. For dynamic documentation that requires runtime interactivity, you might be better served by something like Docusaurus or MkDocs with a plugin layer, though neither of those matches Tutorial Simple's build speed for large collections of plain markdown.
