mini-tutorial.js manual

Example and documentation for mini-tutorial.js

Basically your are looking at it right now. mini-tutorial.js is a clean and simple JavaScript application (consisting of only one class and some style sheets), which allows you to create beautiful HTML-based documentation and tutorials without much effort. All content is contained in a single HTML file using plain and simple HTML markup.

The JavaScript part renders a simple Table of Contents, a few navigation links at the bottom and makes sure that only one chapter at a time is visible. This allows the reader to read the document like a simple book without much scrolling. Also this makes larger documents appear not as overwhelming and be easier to navigate.

Originally I created mini-tutorial.js for my lectures at DHBW Karlsruhe when I needed a simple template to create online tutorials for my students. It is, if you will, the little sister of my other project lecture-slides.js, which is a full-blown HTML slideshow maker with a twist. As such both projects share the same keyboard shortcuts and basic appearance.

This manual of course has also been written with mini-tutorial.js. So just by reading some of its chapters you already get a good feeling of what mini-tutorial.js and how it looks like. But if you like you can completely change the looks of your documents by writing your own style sheet. With mini-tutorial.js you have all the freedom you want, because at the end of the day it still is just HTML, CSS and tiny little bit of JavaScript.

Of course you can easily navigate between chapters with your mouse or the touchscreen on mobile devices. Software developers however also appreciate keyboard shortcuts. So here you are. They shortcuts are the same as for lecture-slides.js, where I have simply copied the code from:

Go, give it a try!

Getting startet with mini-tutorial.js is easy. Just grab one of the following templates from GitHub and off you go:

These projects contains everything you need to write your own documents:

Simply download one of the templates by clicking Clone or download » Download ZIP on its GitHub page and extract it anywhere on your computer. Then start by editing the following files:

That's all there is. While working on a document you will finde the following commands useful (executing them on the command line from within the project directory, of course):

When done, build the document and upload the content of the dist-directory to a web server.

Adding new chapters is easy. Here you can see how the template HTML file looks like:

                
                    <!DOCTYPE html>
                    <html lang="en">
                        <head>
                            <meta charset="utf-8" />
                            <title>__Document Title__</title>
                            <script src="index.js"></script>
                        </head>
                        <body class="hidden">
                            <!-- Page Header -->
                            <header>
                                <h1>__Document Title__</h1>
                                <p class="subtitle">
                                    Catchphrase or subtitle of the document
                                </p>
                            </header>

                            <main>
                                <!-- Table of Contents -->
                                <section id="toc" data-title="Table of Contents"></section>

                                <!-- Document chapters -->
                                <section data-chapter data-title="First Chapter"> <!-- optional -->

                                <section data-title="First Heading">
                                    This is page one.
                                </section>

                                <section data-title="Second Heading">
                                    This is page two.
                                </section>

                                <!-- Navigation -->
                                <nav></nav>
                            </main>

                            <!-- Copyright -->
                            <footer>
                                © Your copyright information here
                            </footer>
                        </body>
                    </html>
                
            

As you can see, each chapter is just a <section> element with a data-title attribute. The title will be shown on the Table of Contents and above the chapter's content. Simply add more <section> elements to add new chapters and watch your browser automagically reload the page.

All other HTML elements can be changed as you wish to apply some chrome. Just leave the <section id="toc"> and <nav> in place to get a Table of Contents and the navigation links.

Well, it hasn't. If you like you can simply copy the files mini-tutorial.js and themes/*.css over to your project and create static HTML page without any external dependency at all. The template project however uses shelljs and parcel-bundler to provide some minimal cross-platform tooling.

Having npm and these two dev-dependencies in place you don't have to duplicate the mini-tutorial.js code for each and every document. Also you get a live preview in your browser with hot-reloading and a minified and pruned JavaScript bundle with mini-tutorial.js and all other JavaScript libraries you might want to use for free.

As an example consider this document. On the previous page we had a syntax highlighted code box. All I had to do was to add highlight.js as another dev-dependency.

npm add --save-dev highlight.js

Then I only needed to change src/index.js to this:

                
                    import MiniTutorial from "mini-tutorial.js";
                    import mtTheme from "mini-tutorial.js/themes/white.css"; // Must be first!
                    import mtCommonCSS from "mini-tutorial.js/themes/common.css";

                    import hljs from 'highlight.js/lib/highlight';
                    import hljsLangXML from 'highlight.js/lib/languages/xml';
                    import hljsLangJS from "highlight.js/lib/languages/javascript";
                    import hljsStyle from "highlight.js/styles/atom-one-light.css";

                    window.addEventListener("load", () => {
                        let mt = new MiniTutorial();
                        mt.start();

                        hljs.registerLanguage("html", hljsLangXML);
                        hljs.registerLanguage("javascript", hljsLangJS);
                        document.querySelectorAll("pre code").forEach(el => hljs.highlightBlock(el));
                    });
                
            

By importing highlight.js from src/index.js Parcel takes care of the rest. The new library will be included in the final JavaScript bundle and all unused parts of it will automatically be stripped. The final bundle will then be minified to conserve even more bandwidth. Code listings can then be insterted like this (note the data-gobble attribute which eats all leading whitespace):

                
                    <pre data-gobble>
                        <code class="html" data-gobble>
                            <!-- Insert HTML code here -->
                        </code>
                    </pre>
                
            

It's just a tiny bit of tooling which makes a huge impact. Bravo to the Parcel developers!

If you import the themes/common.css as in the previous example, the following commonly used markup utilities will be available:

Auto-numbered figures

                
                    <figure>
                        <img src="image-file.png" class="border" />
                        <figcaption>Caption Text</figcaption>
                    </figure>
                
            
Auto-numbered figures, what's not to like?
Image Source: Pixabay: Free-Photos

In order to use another text instead of “Fig.” before the figure number, overwrite it in your custom stylesheet with the CSS variable --figure-short-code like this:

                
                    :root {
                        --figure-short-code: 'Abb. ';
                    }
                
            

Big skip between paragraphs

In case you need a big skip between two paragraphs, akin to the LaTeX command \bigskip, you can use this:

                
                    <div class="skip"></div>
                
            

Filenames, Commands, Screen Output, Keyboard Codes

Technical documents often need to describe keyboard codes, file names, commands or an output the user sees on screen. These can be marked up like this:

                
                    Edit file <span class="fn">file name</span>. <br />
                    Enter command <span class="cmd">command</span> <br />
                    The screen will show <span class="scr">some output</span> <br />
                    Then press <kbd>META</kbd>+<kbd>Q</kbd> to quit.
                
            

The result will then be:

Edit file file name.
Enter command command
The screen will show some output
Then press META+Q to quit.

Vertical alignment in tables

Table contents will automatically aligned to the top, courtesy of this CSS rule:

                
                    td {
                        vertical-align: top;
                    }
                
            

If you look closely at package.json in the template project, you will see that the parcel bundler is called with a src/*.html glob pattern. This makes it easy to build several projects from the same source tree. Simply copy the src/index.html file and create as many HTML files as you want to build documents.