spock.1

.TH SPOCK 1 "SEPTEMBER 2014" "spock 0.4.0" "Spock Manual"
.SH "NAME"
Spock \- a simple Markdown-powered wiki engine
.SH "SYNOPSIS"
.B spock
[\-help] [\-config=<file>] [\-address=<address>] [\-init]
      [\-datadir=<path>] \-repo=<path>
.SH "DESCRIPTION"
\fBSpock\fR is a simple wiki engine heavily inspired by GitHub's Gollum and is
mostly intended as a personal documentation system. Wiki pages can be written
in \fIMarkdown\fR and \fIRestructuredText\fR, although the former is the
preferred format because it can be rendered without relying on third-party
utilities.

Some Markdown extensions are supported:
.IP \[bu] 2
.B Intra\-word emphasis suppression
.IP \[bu]
.B Tables
.IP \[bu]
.B Fenced code blocks
.IP \[bu]
.B Autolinking
.IP \[bu]
.B Strikethrough
.SH "OPTIONS"
.TP
.BR \-config =\fIFILE\fR
Use the configuration file specified by \fBFILE\fR.
.TP
.BR \-repo =\fIDIR\fR
Set the path to the wiki repository. It can be an absolute path or relative
path to current working directory.
.TP
.BR \-init
Initialize a wiki repository in the directory specified by
\fB\-repo\fR=\fIDIR\fR.
.TP
.BR \-address =\fIADDRESS\fR
Set the address and port where Spock will serve the wiki; \fBADDRESS\fR can
specify both the listen address and port (\fI127.0.0.1:8080\fR) or just the
port (\fI:8080\fR).
.TP
.BR \-reindex
Refresh the full-text search index on program startup.
.SH "CONFIGURATION FILE"
The configuration file is a \fIJSON\fR document; inside it you must specify
at least the \fBsecret key\fR, which is used to protect session cookies and
other stuff.

An example configuration file looks like:
.PP
.RS 0
{
.RS 0
    "secret_key": "2b2fc5cc5e1a6ceba39328a9f8659ca5"
.RS 0
}

To create a \fIsecret_key\fR you can use a password and \fBmd5sum\fR, for example:
.PP
.RS 4
$ echo \-n "my long password" | md5sum
.RS 0
2b2fc5cc5e1a6ceba39328a9f8659ca5
.SH "WIKI PAGES"
A wiki page can link to one or more wiki pages; links can be absolute o relative
to the current \fIwiki directory\fR. An example link in \fIMarkdown\fR format
to the \fBDebian\fR page can be written as:
.PP
.RS 4
[Debian notes](debian)
.SS PAGE HEADER
Each wiki page can include an optional \fBYAML\fR header containing metadata
informations about the page. At the moment only the \fBmarkup\fR and
\fBlanguage\fR properties are supported. The header must begin and end with
a line containing only three dashes.

An example header:
.PP
.RS 4
---
.RS 0
markup: "rst"
.RS 0
language: "it"
.RS 0
---
.RS -4

The \fBmarkup\fR property can be set to \fBrst\fR or \fBmarkdown\fR to specify
the markup used in the page; this can usually be omitted as common file
extensions are used to identify the markup of a page (e.g. \fB.rst\fR and
\fB.md\fr).

The \fBlanguage\fR property is used to specify the language in which a page
is written, to aid the full-text search. Currently only \fIItalian\fR and
\fIEnglish\fR languages are supported.
.SH "FILES"
.TP
.BR templates/
All the \fIHTML\fR templates used to render the wiki pages are stored here.
.SH "AUTHOR"
\fBSpock\fR is written by Daniel Kertesz <\fBdaniel@spatof.org\fR> but it could
not have been possible without the authors of the third-party libraries; you
can find more informations in the \fBAUTHORS\fR file.
.SH "SEE ALSO"
Gollum \fBhttps://github.com/gollum/gollum\fR, \fBpandoc(1)\fR,
\fBblackfriday\fR markdown renderer \fBhttps://github.com/russross/blackfriday\fR.