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.
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.
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.
To learn how NanoDocs works, try working through the example project.
There are three steps to creating documentation with NanoDocs:
We'll work through each of these steps by creating some documentation for the classic game Minesweeper.
Continue
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.
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.
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
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.
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 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 will contain two things:
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.
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.
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
Let's flesh out our Minesweeper documentation by adding in some images from the game.
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.
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.
Continue
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 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:
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.
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.
Continue
If you followed this guide all the way through, you should now understand the basics of working with NanoDocs.
Try the following:
For more ideas, check out the following topics:
Continue
The default NanoDocs theme. It's designed to be used for documentation, but can also function as a simple static website.
A minimal theme designed for longer content, such as digital books.
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.
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.
NanoDocs supports normal Markdown link syntax, as detailed in the Markdown syntax guide.
To link to another page in your documentation, use the following format:
[Link text](#folder+file+subheading)
Each of the three components detailed above must be formatted in lowercase.
NanoDocs supports a special form of link syntax that allows you to create links to the next/previous page in a particular folder.
Next page:
>> Link text here
Previous page:
<< Link text here
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:
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".
Enables the download option for the documentation.
Default value is true.
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.
Determines whether folder submenus are expanded by default in the selected theme.
Default value is true.
Determines whether next/previous page icons are displayed in the selected theme.
Default value is false.
Determines whether link icons are displayed by level two headers in the selected theme.
Default value is true.
Specifies the name of the theme to use.
Options:
Default value is default-docs.
Determines the initial font size on loading documentation.
Options:
Default value is small.
Specifies the initial colour variant of the selected theme.
Options:
Default value is mid.
Sets the title of the documentation.
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"
},