01-introduction.md

Introduction

This documentation can be viewed using dawg itself, to follow a well known mantra: eat your own dawg food

dawg is a small tool for converting and viewing markdown documentation files, called chapters. A simple example of this is dawg's own documentation, which lives in the docs directory of the project. It has the following structure that produces this documentation when viewed with dawg:

docs
  |- 01-introduction.md
  |- 02-usage.md
  `- 03-integration.md

Each file is treated as a chapter. These chapters are indexed and parsed using a markdown parser which also supports Github Flavored Markdown.

The numbers at the beginning of each file are meant to sort the chapters. dawg does not know or support ways to sort chapters, it uses the order on the filesystem for this.

Files can be either converted and written to an output directory or served using a webserver. For more usage information see the usage chapter.

Goals

The main goal is to be a simple tool for view your markdown documentation, either while you are writing or when presenting it to others. It should be customizable to fit specific situations but stay interchangeable with other systems and tools.

First of all dawg should be dead simple to use and to get started with. It uses sensible defaults and starts as unobtrusive as possible. dawg can be run without parameters and will not get in your way. Files are served from a default directory and you can get right to writing or viewing your documentation.

When the default configuration is not sufficient dawgs behaviour is easily customizable through the commandline interface. By specifying options on the commandline you can change or extend the default behaviour to your specific situation.

Finally dawg does not impose any syntax in your documentation files. It supports plain markdown syntax with Github Flavored Markdown as an optional extension. Any features that are specific to dawg will be supported through the rendering layer, not through the syntax of the documentation files. This way dawg is able to work with existing documentation files and is interchangeable with other systems that can display or convert markdown, like GitHub's website or tools like markdoc.

Need fancy features?

dawg is meant to be a simple tool. If you are missing some features, or if you require more advanced features you might consider using a more advance tool, like Sphinx or Docbook.