Gaiden is a tool that makes it easy to create documentation with Markdown. It assumes familiarity with the command-line. The Groovy language is the base of the tool.
You need a Java SE installed, but it is not necessary to install Groovy because it's bundled with the Gaiden distribution.
Installing Gainden on Unix based systems is easiest with GVM:
$ gvm install gaidenOr download a binary distribution of Gaiden and unpack it into some file on your local file system.
Add the bin directory path in unpacked the distribution to your PATH environment variable.
Then in a shell, type the following:
$ gaiden create-project sample-project
$ cd sample-project
$ gaiden buildYou can see the documentation built when you open build/index.html file in your web browser.
The basic usage is:
$ gaiden <command name>- create-project <project name>
-
The starting point for Gaiden.
The
create-projectcommand creates the project directory using the <project name> specified by user. - build
- The
buildcommand builds HTML pages from Markdown files using templates, and copies static resources. - clean
- The
cleancommand deletes all built and copied resources.
build/- Built documents and static resources will be placed under this directory.pages/- The place of source Markdown files. The directory layout will be kept when it is placed in thebuilddirectory.toc.groovy- The table of contents written by DSL. See ToC.
static/- The place of static resources. All of the files and subdirectories will be copied under thebuilddirectory.templates/- The place of template files. See Template.GaidenConfig.groovy- The configuration file. See Configuration.
The cool template is provided by default in Gaiden.
Alternatively, if you don't like it very much, you can customize the template.
To customize the template, you will need to edit the templates/layout.html file.
The most simple template is the following:
<html>
<head>
<title>$title</title>
</head>
<body>
$content
</body>
</html>You can use extension properties and methods which start with $ in the template.
It can be used to refer to variables or run helper methods.
Gaiden supports the following extension properties and methods by default:
- title
-
A title of a documentation which can be configured in
GaidenConfig.groovy:<title>$title</title>
- content
-
A content of html which is generated from a Markdown source in the
pagesdirectory:<body> $content </body> - resource
-
Creates a link to the static resources, e.g. image, css and javascript:
<html> <head> ... <link rel="stylesheet" href="${resource('/css/main.css')}"> <script src="${resource('/js/jquery.min.js')}"></script> </head> <body> <img src="${resource('/img/logo.jpg')}"/> ... </body> </html> - tocPath
-
Create a link to the table of contents page:
<a href="$tocPath">Table of Contents</a>
Gaiden provides settings for generating the document in 'GaidenConfig.groovy'. You can customize behavior by changing settings.
- title
- Base title of page.
- tocTitle
- The title of TOC.
- templateFilePath
-
The path of template file.
default:
templates/layout.html - tocFilePath
-
The path of TOC file.
default:
pages/toc.groovy - tocOutputFilePath
-
The path of TOC output file.
default:
toc.html - pagesDirectoryPath
-
The path of page source files directory.
default:
pages - staticDirectoryPath
-
The path of static files directory.
default:
static - outputDirectoryPath
-
The path of directory to be outputted a document.
default:
build - inputEncoding
-
The encoding of input Markdown resource.
default:
UTF-8 - outputEncoding
-
The encoding of output document.
default:
UTF-8 - templatePath (deprecated)
-
Please use
templateFilePathinstead. - tocPath (deprecated)
-
Please use
tocFilePathinstead. - tocOutputPath (deprecated)
-
Please use
tocOutputFilePathinstead. - pagesDirectory (deprecated)
-
Please use
pagesDirectoryPathinstead. - staticDirectory (deprecated)
-
Please use
staticDirectoryPathinstead. - outputDirectory (deprecated)
-
Please use
outputDirectoryPathinstead.
NOTE: The encoding of GaidenConfig.groovy must be same as the file.encoding system property.
If you want to use another encoding, you can use JAVA_OPTS or GAIDEN_OPTS to pass JVM options to Gaiden as follows, for Unix:
$ export GAIDEN_OPTS="-Dfile.encoding=Shift_JIS"for Windows:
> set GAIDEN_OPTS="-Dfile.encoding=UTF-8"
Create pages/toc.groovy file which defines document structure if you need a table of contents.
You can write it with DSL support as follows:
"introduction.md"(title: "Introduction")
"quickstart/quickstart.md"(title: "Quick Start")This file also defines the section titles using the title attribute.
If you have nested pages, you can use block:
"introduction.md"(title: "Introduction") {
"introduction/whatis.md"(title: "What is Gaiden?")
"introduction/install.md"(title: "Install")
}
"quickstart/quickstart.md"(title: "Quick Start") {
"quickstart/addingcontent.md"(title: "Adding content")
}If you don't know the Markdown, please refer to Markdown Syntax Guide at Daring Firebal.
Gaiden uses PegDown as a Markdwon library under the hood. In addition, Gaiden provides some syntax support.
You can use an absolute path from a static resource directory in a path of image syntax. For example:
Gaiden automatically generates relative a path from an absolute path which is specified.
Gaiden is licensed under the terms of the Apache License, Version 2.0