snowie-docs

A one page documentation generator libary

Usage no npm install needed!

<script type="module">
  import snowieDocs from 'https://cdn.skypack.dev/snowie-docs';
</script>

README

Introduction

Snowie Docs is a tool to generate single page html files from your documentation. It is light weight easy to use CLI app. It generates a single html, with no js or css files attached which you can edit and you can host anywhere, like Github Pages.

Install

Npm:

run npm i -g snowie-docs to install

Documentation

basics

Firstly Snowie is a CLI app so you will use the command snowie.

cli

init

Running snowie init <your project name>, will create a directory with the basics.

help

Running snowie help, returns commands

ver

Running snowie ver, returns current version

build

Running snowie build, snowie bake or snowie b, will build the html for you to your output directory

Build Config

To start of you need a snowie.build.json in it this the below will be your basic setup

{
    "title": "Basic-Snowie-Docs",
    "name": "Basic Snowie Docs",
    "description": "a basic snowie doc template",
    "markdown_engine": "markdown-it",
    "render_engine": "md",
    "markup": "md",
    "out": "output",
    "in": "index.md",
    "out_name": "index",
    "files": "./files",
    "links": [
        "Basic-Snowie-Markdown-file"
    ]
}

options

  • title: [type=string] the title of the project
  • name: [type=string] the title for the output file.
  • description: [type=string(optional)] the description of the project
  • markdown_engine: [type=string(optional)]Options: markdown-it | showdown: the compiler that will be used to compile the markdown, choose the one that suits your need, Read More
  • render_engine: [type="string]Options: md | html: the render type that will be use when you load the page, Read More
  • markup: [type: string]Options: md | html: the markup language you will use to write this documentation, Read More
  • out: [type="string"] the output folder
  • in: [type="string"] the input markup file
  • out_name: [type="string"(optional)] the output file name
  • files: [type="string"(optional)] the location of the files that will be bundled with the page, a folder in which for example your images will stay in, Read More
  • links: [type="array"] a array of links within the page, Read More
  • snowie-engine: [type="string"(optional)] snowie docs compiler option

Render-engine

The render engine is how the page will be rendered.

md will give a markdown file to the page which will be compiled the html using the markdown_engine of your choice and then put on to the page, so it will take some time to compile once the page is loaded.

html will compile the input markup to html and paste it onto the page which will be loaded once the page will be opened, it is more faster but complicated and long documentation will take time to load for the user specially on slow systems.

Markdown engine

The markdown engine gives the choice of features you want when you compile your markdown and when using the the markdown. The first, also recommended, is markdown-it which uses the CommonMark Spec, and then the showdown is used in many places,seen here, so its your choice which to use, but you have to define it if you want to use markdown in the render_engine. and the Markup

Links

Links are the links that appear on the side of the page. for them to link to contents on the page.

setup

{
    "href": "<the link on the page>",
    "name": "<the name for the link>"
}

example:

{
    ...
    "links":
    {
        "href": "example",
        "name": "example link name that will show up in the side bar"
    }
    ...
}