Light Mid Dark

Introduction

What is NanoDocs?

NanoDocs is a tool for generating online documentation.

You write your documentation in Markdown format, and NanoDocs combines the files into a single-page app that you can host wherever you like.

The documentation you're reading right now was generated using the NanoDocs default settings.

Why a single-page app?

If your documentation exists as a collection of multiple web pages, users can't access it offline.

NanoDocs allows users to download your documentation (including images) as a single HTML file, which can be opened by any browser without the need for an internet connection.

Look and feel

NanoDocs ships with multiple themes, each of which supports multiple colour modes and text resizing.

Take a look at some examples in the themes guide.

Getting started

To learn how NanoDocs works, try working through the example project.

Getting Started

There are three steps to creating documentation with NanoDocs:

  1. Download and configure NanoDocs
  2. Add documentation files
  3. Build the documentation

We'll work through each of these steps by creating some documentation for the classic game Minesweeper.


Continue

Get and Configure NanoDocs

NanoDocs can be used as a standalone project, or as part of an existing project.

For this example, let's begin with a new project.

Downloading NanoDocs

NanoDocs is available via npm. To get it, run the following command in the root directory of your project:

npm i nanodocs

Alternatively, you can get the code by cloning the GitHub repo.

Configuring NanoDocs

Before writing any documentation, NanoDocs needs to be initialised.

Run the following command in the root directory of your project:

npx nanodocs init

This command creates a new directory called nanodocs with the following structure:

nanodocs
|   config.json
|
└── build
└── contents
    └── assets
    └── documentation

We'll see what each of these items is used for in the following sections.


Continue

Add Documentation Files

Now that we've downloaded and configured NanoDocs, it's time to write some documentation.

If your memory of the rules of Minesweeper is a bit rusty, check out the Wikipedia entry for a reminder.

The documentation folder

When we configured NanoDocs in part one of this guide, a new folder called nanodocs was created in the root directory of our project.

Inside is a subfolder called contents, which looks like this:

contents
└── assets
└── documentation

The documentation folder is where our documentation files will live.

Documentation files are in Markdown format, so if you're not familiar then take a minute to check out the Markdown syntax guide.

Documentation structure

Documentation files can live in the root of the documentation folder, or grouped into subfolders. Subfolders within subfolders are ignored by NanoDocs.

Here's the structure we'll be using for our Minesweeper documentation:

documentation
|   introduction.md
|
└── gameplay
    |   basic rules.md
    |   difficulty levels.md

Go ahead and replicate this structure in your documentation folder.

The introduction.md file

The introduction.md file will contain two things:

  1. a brief description of the documentation
  2. a link to the Minesweeper Online game

Go ahead and copy/paste the following into the file:

# Introduction

This documentation contains the basic rules for the classic game **Minesweeper**.

[Minesweeper Online](https://minesweeperonline.com/#beginner) is a free version of Minesweeper that you can play in your browser.

The first line in this page is a level one Markdown heading. This heading is used by NanoDocs to create links to each page of our documentation, so it's required.

The second and third lines make up the contents of the page: a description of the documentation, and a link to the Minesweeper Online game. The Markdown syntax guide has more detail on how to create links.

The gameplay pages

Copy/paste the following into the basic rules.md file:

# Basic Rules

## About the game

The object of the game is to uncover all the squares on the grid that don't contain mines.

The game is completed by clicking on all squares that don't contain mines.

Clicking on a square that contains a mine is game over.

## Numbers

Clicking on some squares reveal numbers. These numbers indicate how many of the surrounding eight squares contain mines.

## Flags

You can "flag" the location of suspected mines to remind you not to click on them.

## Controls

- Use the left mouse button to click on a square
- Use the right mouse button to flag a square

...and the following into the difficulty levels file:

# Difficulty Levels

## Beginner

- Height: 9
- Width: 9
- Mines: 10

## Intermediate

- Height: 16
- Width: 16
- Mines: 40

## Expert

- Height: 16
- Width: 30
- Mines: 99

Note the required level one Markdown headings in each file.

As always, you can check out the Markdown syntax guide for more information on the other syntax used.

Next steps

Our documentation folder now contains an introduction page, a subfolder, and two further pages within the subfolder. This is as much as we need for now.

Continue

Add Documentation Images

Let's flesh out our Minesweeper documentation by adding in some images from the game.

The assets folder

Inside the nanodocs folder we created in part one of this guide is a folder called contents, which looks like this:

contents
└── assets
└── documentation

The assets folder is where our images will live.

Adding images

Let's add a gameplay image to our introduction page.

Save the following image to your assets folder:

Then, add the folling line right below the level one header of the introduction.md file:

![Minesweeper](minesweeper.png)

The section in square brackets is the image's alt text, and the section in round brackets is the image path. Note that the image path is relative to the assets folder.

You can read more about including images to Markdown in the Markdown syntax guide.

Your introduction.md file should now look like this:

# Introduction

![Minesweeper](minesweeper.png)

This documentation contains the basic rules for the classic game **Minesweeper**.

[Minesweeper Online](https://minesweeperonline.com/#beginner) is a free version of Minesweeper that you can play in your browser.

By default, NanoDocs inlines images into the output HTML file. You can read more about how this works, as well as how to override this behaviour in the images guide.

Next steps

Continue

Build the Documentation

We're almost ready to build and view our documentation.

Before that, we just need to tell NanoDocs how we want our documentation to be built.

The config.json file

The config.json file is located in the nanodocs folder that we generated in part one of this guide.

In this file, we can pass options to NanoDocs that determine how our documentation is built. We also tell NanoDocs which of our Markdown files we want to include, and in what order.

Right now, it should look something like this:

{
    "title": "",
    "docs": [
        
    ]
}

Let's start by editing the title field to give our documentation the title Minesweeper. This will be displayed at the top of the documentation page:

"title": "Minesweeper"

We'll now add some items to the docs array, which tells NanoDocs which of our Markdown files to include:

"docs": [
    {
        "folder": "root",
        "files": [ 
            "introduction" 
        ]
    },
    {
        "folder": "gameplay",
        "files": [ 
            "rules",
            "difficulty levels" 
        ]
    }
]

Each entry in the docs array is an object that contains the following properties:

  • folder - the name of the folder containing the Markdown file(s) you want to include
  • files - an array containing the name of each Markdown file within the folder you want to include

We use the special folder name root to refer to files that live within the documentation folder itself, such as our introduction file.

That's it for the config.json file.

Running the build

To build the Minesweeper documentation, run the following command in the root directory of your project:

npx nanodocs build

So long as the build ran successfully, your documentation can be found in the nanodocs/build folder. Try opening it with a browser and using the menu to navigate between pages.

Next steps

Continue

Taking it Further

If you followed this guide all the way through, you should now understand the basics of working with NanoDocs.

Developing the Minesweeper project

Try the following:

  • Adding more pages
  • Changing the order in which pages appear by editing the config.json file
  • Adding more images
  • Adding links to external websites

Advanced usage

For more ideas, check out the following topics:

Continue

Themes

docs-default

The default NanoDocs theme. It's designed to be used for documentation, but can also function as a simple static website.

  • Responsive design
  • Supports font resizing
  • Light, mid, and dark colour variants

book-default

A minimal theme designed for longer content, such as digital books.

  • Responsive design
  • Supports font resizing
  • Light, mid, and dark colour variants

Config options

  • autoExpandSidebar

Images

Inline images

By default, NanoDocs inlines images into the output HTML file.

This means that when users download your documentation, images are included and visible without the need for an internet connection.

Hosted images

If you'd rather host your images, specify the following option in the config.json file:

"inlineImages": false

All image paths must now refer to the source of your hosted images.

Table of Contents

To generate a collapsible table of contents, use the following syntax:

<details><summary>Table of contents</summary>

- [Link 1](#link)
- [Item 2](#link)
- [Item 3](#link)
- [Item 4](#link)
</details>

The generated output looks like this:

Table of contents

Config Options

Table of contents:

docs [array]

Specifies which of the markdown files in the contents/documentation folder will be included in the build.

Each object in the array refers to a containing folder and a collection of files:

{
    "folder": "folder-name",
    "files": [
        "file-1",
        "file-2",
        "file-3"
    ]
}

To refer to files in the root of the documentation folder, use the folder name "root".

downloadEnabled [bool]

Enables the download option for the documentation.

Default value is true.

inlineImages [bool]

Determines whether images are inlined into the output HTML file or not.

For more information on inlined images, see the images guide.

Default value is true.

theme.autoExpandSubmenus [bool]

Determines whether folder submenus are expanded by default in the selected theme.

Default value is true.

theme.docNavButtons [bool]

Determines whether next/previous page icons are displayed in the selected theme.

Default value is false.

theme.linkIcons [bool]

Determines whether link icons are displayed by level two headers in the selected theme.

Default value is true.

theme.name [string]

Specifies the name of the theme to use.

Options:

  • default-docs
  • default-book

Default value is default-docs.

theme.fontSize [string]

Determines the initial font size on loading documentation.

Options:

  • small
  • regular
  • large

Default value is small.

theme.variant [string]

Specifies the initial colour variant of the selected theme.

Options:

  • light
  • mid
  • dark

Default value is mid.

title [string]

Sets the title of the documentation.

With Nodemon

Using NanoDocs with nodemon makes creating documentation extremely efficient.

In your nodemon.json file, tell nodemon to watch for changes to the nanodocs folder, but ignore changes to the nanodocs/build folder:

{
    "watch": ["nanodocs"],
    "ignore": ["nanodocs/build"]
}

The following script can be added to your package.json file to execute a NanoDocs build on any changes:

"scripts": {
    "dev": "nodemon --exec npx nanodocs build"
},