Giterary User Manual

The following document is a user’s manual of sorts for day-to-day user interaction with a working Giterary instance. If you’re having issues with configuration or installation, you should look at the INSTALL document.


Giterary Concepts

Giterary belongs to a family of computer software that calls themselves “wikis.”

What is a wiki?

A wiki is an application that lets you navigate and edit a web of documents and document references from a single interface. The most famous wiki being Wikipedia.” You may have heard of them.

Wikis are powerful tools because they allow you to efficiently organize and navigate your information while providing multiple users the ability to update and maintain the content. They vary in ubiquity and in features, given special use cases, extensibility, and popularity. Giterary’s wiki features are inspired largely by Mediawiki and MoinMoin (both excellent examples of full featured and extensible wiki software).

File Structures and naming


Naming Files

File names can include almost any normal filesystem character (alphanumerics, slash, underscore, spaces) minus a colon (":"), solidus ("/"), and non-printing characters.


All files can be referenced using a file path. This file path refers to the “path” one must traverse through the directory structure of your Giterary repository in order to get to your actual file. Examples would be like the following:

Home                       (the "home page" for your wiki)

Files, Directories, and “Dirification”


Let’s say you have a directory structure like this:

My Story/Chapters/Chapter 1
My Story/Chapters/Chapter 1/Notes
My Story/Chapters/Chapter 1/Citations

The question becomes: What type of object is the thing called Chapter 1?

Chapter 1 is certainly a file, but it’s referred to in the paths to Notes and Citations as a directory path component.

Giterary solves this problem with the concept of “directorification” or “dirification.” It is an abuse of file paths to make it seem like Chapter 1 is both a file and a directory. By way of “dirification” Giterary will treat the following two file paths as equivalently referencing the exact same file:

My Story/Chapters/Chapter 1/Notes
My Story.dir/Chapters.dir/Chapter 1.dir/Notes

In the first file path, it is implied that the path components My Story, Chapters, and Chapter 1 have the suffix “.dir” appended to them because they are being treated as a directory. In the second file path, the “.dir” suffixes are explicit, but refer to the true, “dirified” path.

In this way, there can still be two objects with the “same name,” but only by a quick sleight of hand on Giterary’s part. In this way, you can ask to edit My Story/Chapters/Chapter 1 and My Story/Chapters/Chapter 1/Notes and have it do the right thing.

Creating New Files and Directories

Per wiki software convention, the most common way to create a new file is to edit an existing one with a link to the new page, and then navigating to that link. Giterary tries to adopt this convention, erring on the side of good organizational structure rather than simplicity of just creating a new file. That said, there is nothing to stop a user from just looking at the URL of the file referenced in their browser window and change it to their desired new filename.

An alternate route exists, however: if you browse to any directory, a text input is available, pre-populated with a data structure relevant to the currently viewed directory, and something akin to NewFile appended at the end. This will allow you to easily create files under known directory structures.

Additionally, one can hit the “Jot” button when logged in, which immediately puts the user in the editor for a file that is date-stamped to the current date. This is another way to quickly write in a new file while retaining some information about when that file was created.


A final note on creating new files: if a new file references a path component that does not exist, when finally committing that file Giterary will create all necessary directories in order to place that file on the path specified. For instance, in a blank repository, edits and submits the file “My Story/Chapters/Chapter 5/Notes” it will create the following directories:

My Story.dir
My Story.dir/Chapters.dir
My Story.dir/Chapters.dir/Chapter 5.dir





  • From a given document display, you can select Other Options > Search for …What Links Here, and return all documents that have wikilinks pointing to this page.
  • From the top navigation “TODO” hyperlink when logged in, you can view a list of documents that contain special “TODO” flags within them that indicate work needing done at certain parts of a document. These work for both “TODO” and “TBD” patterns found within documents.

Types of Objects within Giterary


File types are determined by extension

If a file has an extension (MyFile.txt, MyTable.csv,, etc.) that extensions handling (as determined by Giterary) will be used by default when displaying the page (txt or text for purely textual documents, md or markdown for Markdown syntax documents, csv for Comma Separated Values formatted files, and so on).

For files with no extension (Chapter1, 01-Wednesday, HelpFile) a default renderer is chosen, and that renderer is configured to be the Markdown renderer by default. See later in this document for explanations of Markdown.

You can also override the renderer by specifying different “as=someextensionname” on the URL of a document. This is useful for rendering something as its underlying source code (as=text), readable text (as=wrap). For instance, this document as:

Directories are for browsing

On every document, there is a tab called “Directory” that will go to a page listing the contents of the directory with that document’s same “dirified” name. For instance, viewing My Story and clicking on “Directory” will list anything under the directory called My Story.dir.

This is useful for navigation your organizational document structures.

Document Decorations

In addition to the formatting provided by Markdown syntax and other HTMl formatting tags, Giterary also provides additional “decorations” to a document. These decorations are “hidden” by default, but are present in the Giterary interface by selecting the “Decorations” checkbox at the top of a document display, or by hitting the letter “d.”

The decorations currently available are:

  • Annotations (described in the Editing section)
  • Dialog highlighting (described in the Editing section)
  • Invisible headings (these will be described in the Table of Contents section).

Document Tables of Contents


Header Title

…or like this…

Header Title

…or like this…

## Header Title

…you have specified that there should be a “header” element with the text Header Title. This will generate the appropriate HTML element (the h1, h2, h3, h4, h5, or h6 tags) according to the “level” of header. Refer to the Markdown syntax documentation for more complex header generation.

Each of these header elements are then detected by Giterary upon rendering, and can be turned into “bookmarks” as part of an automatically generated table of contents. Depending on your screen geometry (window width of your browser), this table of contents will appear either at the top of your document, or to the right of your document.

Giterary makes one departure from Markdown’s normal “header” output, in that it treats the h6 (header level 6) elements differently. Rather than displaying h6 elements like the rest of the headers, they will be invisible, but still be treated as “bookmarking” elements. With this, you can treat h6 headings as invisible placemarkers within larger documents. This is useful if you want to maintain bookmarks within a document, but not disrupt the formatting of the document with headings.

For example:

###### This is a hidden heading

Will generate a This is a hidden heading table of contents item, but not render within the document (as you should not see below)

This is a hidden heading


Comma Separated Values Files (*.csv files)

A CSV file (Comma Separated Value) file is a file whose content consists of tabular data stored in a text document, with line of text representing a “row” of data, and different columns specified by a list of fields, separated by commas.

For example:

Year,Month,'Day of Month',Note


YearMonthDay of MonthNote
20130118Today I drank beer. Perhaps I drank too much.
20130119Today I drank tea. It's not the same as coffee.

These CSVs will assume the first row of data is “header” data. It will then put it in an HTML table that can be sorted by the user.

One can also specify default sorting methods with the following syntax:

  • !Year sorts the column “Year” in least-to-greatest order.
  • ^Year sorts the column “Year” in greatest-to-least order.
  • !#Year sorts the column “Year” in least-to-greatest order, treating all elements as numbers.
  • !@Year sorts the column “Year” in least-to-greatest order, treating all elements as strings.

You can mix and match the sorting “hints” as you wish.


Collections have the purpose of rendering multiple documents within your Giterary repository at once. This is done as a special rendering of the collection or collect file extensions. Contents of these files are simply lists of other file paths (MyFile, Wherever/I/Put/My/File.txt).

For example:


Will render the files Chapter1, Chapter2, and Chapter3 in succession on a single page. This is useful for stitching together a larger document (the entirety of a book, for instance), of which you have broken into smaller, more manageable pieces (chapters, in this case).




You can also use the collection documents to include an entire subtree of your Giterary repository. For instance, for the user “jrhoades,” they may have a collection that contains the following:


Use of the asterisk wildcard lets you match all documents matching the collection query. Documents will be rendered in order of directory traversal, and in alphanumeric order. The above example will render all “jot” files for the user “jrhoades” for the years 2010-2019.

Document Statistics

Document statistics are your basic “word count"—types of metrics that Giterary will calculate for you. For instance, you can view the statistics for this very help file.

Statistics calculations also work on collection files, such that the statistics will be calculated for the collection document after all of the components of the collection have been collected.

Document Import

Currently there are no “import” tools for Giterary. This is because there are hundreds of tools that can do a better job than Giterary can for the hundreds of files and formats people use outside of Giterary.

For the time being, Giterary maintains that simply rendering your documents into text is sufficient to copy and paste your documents into Giterary. Using tools like OpenOffice, Pandoc, or the two in conjunction to generate Markdown syntax is one successful conversion path used by the author, however, some experimentation may be in order.


If you do manage to get your document into a textual format suitable for Giterary, it is likely that this document is sufficiently large (in the case that you’re submitting a manuscript, or something of that scale).

It may be the case that you want to split up this document into smaller parts for you, your co-authors, or your editors to work on. In this case, Giterary does have a tool for easily “partitioning” files that makes this type of organization much easier.

Partitioning works by finding “potential boundaries” by determining where there are blank lines (or lines with only whitespace) within the body of work. As these blank lines have no content, they are likely things like spaces between paragraphs, chapters, etc.


To see an example, try to partition this file.

Document Editing

Editing a document is probably the most critical and common activity within Giterary. The editor attempts to be straightforward while giving as close to immediate feedback on the things that you’re editing as possible.

The editor

While logged in to Giterary, viewing any object (except for directories) there will be an “Edit” tab at the top of the document. This link will take you to an editor for that particular page. An editor does generally what you expect: it shows you the text contents of a file, and allows you to modify the contents, and save your changes. There are, however, a few things to note about the editor.

  1. The editor is contextually aware.

    That is, the editor detects the type of file that you are editing, and attempts to show an editing interface that is tailored for that type of file. The most apparent (and at time of writing, the most developed) of these contextually aware editing interfaces is that for Markdown. When editing a Markdown file, the interface will display the source text and a “live preview” side-by-side. It will even attempt to provide keyboard shortcuts and formatting buttons that reflect the editor’s capabilities. However, for more generic files, the editor will display a “plain” editing interface without the live preview.

  2. The editor tries to minimize the amount of scrolling you have to do.

    Both the Markdown and generic editors attempt to “synchronize” the editing and preview windows to the best of their ability:


    The editor will also “save your place” in the editing window, allowing you to quickly preview a document without having to scroll back to your place.

  3. The editor is aware of the version of the file you were originally acting against, and tries to help accordingly.


    If ever the editor detects that the file has changed out from underneath you, it will display an error and refuse to save. It does, however, keep your edited contents in the editing window, as well as saves a draft of your edits. Unfortunately, it is up to you to resolve the conflicts occurring from the Giterary interface, but we would rather err on the side of caution by not ever unintentionally overwriting another’s work.

Working within the Editor


Shortcuts and Formatting

Depending on the type of document you’re editing, the editor might give you a number of “shortcut” buttons at the bottom of the editor. These are similar to the toolbars you might see in other editors, but are tailored for the type of document you’re editing.

Each “shortcut” is a combination of either the Control or Alt keys on a keyboard and another single keypress (pressing control or alt first, and then at the same time another key). This “meta” key will be different depending which operating system you’re accessing Giterary from. This is because some systems have other, critical functionality already mapped to these key combinations (and some critical functionality that you cannot or should not customize). For Giterary, Windows and Linux browsers will rely on the Alt key, while Mac OS X browsers will rely on Control. The shortcut bar will indicate which beginning key you should press (either “Control + …” or “Alt + …” at the bottom of the editor).

Each shortcut button shows two things:



If you have highlighted something, the shortcut buttons will usually attempt to apply the corresponding formatting to the text you have selected. This is useful if you’ve already typed out text and wish to apply formatting at a later time.

If you haven’t highlighted anything and just have a normal cursor, an example of the corresponding formatting will be inserted into your editing window with a section highlighted that you need to edit yourself to complete the formatting. This is useful if you want to make use of formatting, but either don’t want to type the syntax required to do so, or forget how the syntax works.





For example:


Turns into something like this:


You can also specify “display” text along with your link, like so:

[[ANameOfYourDocument|Click here to view my document]]

Which turns into something like this:

Click here to view my document



Functional Links

In addition to “wiki"—style links, you can use “functional” linking syntax to generate links that perform functions around Giterary. These involve using a known “prefix” based on Giterary functions, and specifying the parameters that would be used within that link. For instance, determining the “diff” between two commits within Giterary might look like this.


Would render to…

Changes caused by HEAD commit



Note: Annotations are “hidden” by default, and only appear when you enable decorations. If you are browsing from Giterary, hit the “Decorations” button at top, or hit “d” to enable the examples below.

    This text is annotated.

Renders to this:

This text is annotated.This text is “annotating” the original text.

Note that with the above syntax, you need not put the “comment” tags at the end of the “annotate” content, nor are you limited to one comment tag within the annotation.

There is also a simplified syntax for this that allows you to provide minimally disruptive annotation syntax in your content, and specify your annotation text either explicitly next to the annotate or later in the document (allowing for a “reference” section, similar to the Markdown feature of allowing the definition of a URL to be apart from its usage.




...and elsewhere in the document...

{referencetag}: This is my note.

Would generate the following:

This is some annotated text.This text is annotating


This is some annotated text.This text is annotating.

The editor has a helper function to quickly generate annotations. While highlighting a section of text, clicking on the “Annotate Selected Text” hyperlinks will prompt you for your annotation comments.

Dialog Highlighting


Dialog content generally follows the format of:

“Something something,” she said.

Which consists of:

  • Content with double quotes, and…
  • Not part of a “list” ("Item 1,” “Item 2,” and “Item 3").




To quote the author:



This Help document is written in Markdown format. You can view its contents by selecting Other Options > …Readable Text when displayed in Giterary.


Additional Note: One of Markdown’s features is that it will allow HTML tags to be embedded within it (to provide features that Markdown can’t provide). Giterary supports this “HTML pass-through,” however, only for a limited subset of HTML (for security reasons).

Commit Notes

On every editor there will be a “commit notes” field. This field consists of plain text, without any formatting or special syntaxes. This is because this field is intended to record the reasons or reasoning behind your current modifications. Feel like you’re using the word “bustle” too many times? Put it in the notes. Moving some things around to sound more punchy? Put it in the notes. Did it start snowing while you were writing? Put it in the notes.



Preview vs. Commit vs. Commit and Edit

While the commit notes for editing are not mandatory, an immediate preview of your document before committing your changesis. This is for a few reasons:

  • There may be in the future elements in the editor that require server-side processing (and therefore, require a “Preview” to be able to see the render properly).
  • To make sure the file hasn’t changed out from under you.

You can commit in one of two ways:

  • Commit, which commits your modifications and then redirects you back to view the file normally.


When editing a document, a timer will periodically trigger to determine if you have made significant changes in the editor. If so, it will send a “draft” portion back to the Giterary server, containing the contents and the commit against which the draft was being written.

These drafts can be used to recover writing lost after the disruption of an Internet connection, power failure, or a failure to distinguish “Control-W” from “Control-Q” as a keyboard command.

These commits can be recovered by logging in and visiting the “My Drafts” page, which will list all recent unsaved drafts. Clicking on “edit” for a draft from here will load the editor page with the last known draft contents against the document you were editing.

The Wonderful World of Version Control

git provides powerful tools to allow you to see and manage the changes to your documents over time. Giterary’s functionality only brushes the surface of git’s myriad uses, and this author would highly recommend you explore its features for use in your writing projects and any others where text could benefit from version control.

git in a Nutshell


git stores its data as specially organized files alongside the files you ask it to track. This means that while git is a database, its contents are still files, which can be stored, moved, and copied, just like any other files on your computer. This specially organized git directory structure is normally under a directory called .git. Locations on your computer with these .git directories are called repositories.

Giterary allows you to edit and maintain your git repository from a web interface. However, many git client applications are available to do this, and implement larger portions of git’s functionality. We recommend investigating some of these clients in order to take advantage of git’s more advanced features.

Terms from git


  • commit: A “commit” is a set of changes successfully made and recorded to a git repository. Commits can contain many types of changes, including:

    • File modifications (to one or more files)
    • File creation (for one or more files)
    • File deletion (for one or more files)
    • Moving a file (or a directory structure)
    • Branch merges (referring to a feature of git called “branching,” where totally different versions of a file structure are stored in the same git repository, and they are combined togther). Note that branching is not currently supported in Giterary.
  • log or history: A list of commits stored in the repository, often listed in chronological order.

  • difference or diff: A feature of git which can compare any two files and programmatically determine similarities and differences, and display them to the users. Often the output of this feature is called a diff as well as the process for generating a diff.



Giterary can query your repository’s historical log of changes, listing them by commit in reverse chronological order (latest changes first). The history page (available by clicking “Log” in the top navigational element of the Giterary interface) queries the log and displays the results that match your criteria. By default, it shows all changes for all files and all users.


  • You can click on “My Commits” while logged in to see a list of only commits which you were responsible for. ("Show me only my commits.")
  • While viewing a file, you can click on the “Revision History” to see a list of commits involving only your viewed file. This works for all files, as well as files which have been renamed at some point in their turbulent past. ("Show me everything that happened to this file.")
  • While browsing history, you can click on either the “hist” link on a given row to see a history of the files included in that commit ("Show me the history of all the things that this change touched.")


To demonstrate, you can view the history of this file..



To do so, use the repository history to find the commit which you wish to revert. Select the commit’s unique SHA number (under the commit heading). This will bring up a details page on the commit itself, showing author, notes, and the contents of the changes in the commit. If you are logged in, at the bottom of this display is a “Revert this commit” button, which after confirmation, will revert all changes within the specified commit back to their original states. This does not, however, eliminate the history of the repository afterward, it instead generates a new commit whose contents revert the changes.

Comparing Different Versions, or “Diffs”

As described, a “diff” is a programmatic determination of the similarities and differences between two files, or two directory structures. Diffs are used frequently in software development and configuration management scenarios when file modifications must be performed in an automated fashion.

For Giterary, diffs are valuable because they can show the differences between two versions of a file, demonstrated as either additions and subtractions as a result of the modifications necessary to bring one version of the file in sync with the other version of the file. To make viewing and manipulation of diffs easier, Giterary calculates diffs on a “longest word sequence” basis, saying “I added this sentence to the end of this paragraph” rather than “I added 20 words to the end of this paragraph.” This becomes important when using diffs in conjunction with other features (cherrypicking, specifically).

You can calculate diffs in a few ways:

  • When viewing a file, you have the option of selecting Other options > Compare …to previous version or Other options > Compare …to previous version (no formatting). The former version attempts to format the resulting additions and subtractions for a diff in the renderer appropriate for the file’s extension, and the latter formats the diff in plain text. Formatting a diff sometimes helps with readability, but additions and subtractions to formatting elements can cause rendering artifacts, in which case, plain text diffs are more readable.
  • When viewing history (and with any of the available history filtering options) you can select specific “before” and “after” versions beneath the “show diff” button, and show the resulting diff calculation by hitting the “show diff” button.
  • When viewing history, you can select the “head” hyperlink to compare your selected version to the latest “head” version of a file.
  • When viewing history, you can select the “prev” hyperlink to compare that commit’s “parent” commit against the “child” you selected.

To demonstrate, you can view the changes that last occurred to this file.


Cherrypicking is the concept of taking the output of a diff (with its “additions” and “subtractions") and choosing to keep or discard any number of modifications. This allows you to “revert” changes to a file but on very specific basis (down to reverting single word changes, if necessary).

While logged in and viewing a document, you can select Options > Cherrypick last change to bring up a similar interface to the plain diff action. By selecting the adds/removes in the text in the left column, you toggle whether you will keep or discard that change, and the display in the right column will reflect your choices. When you are done, you can hit the “Put changes in editor” button to put your newly kept/discarded elements into a text editor for further editing.

Even while not intending to cherrypick, this can still be useful for reviewing changes to a document as it provides a “Next Difference” button, which cycles through the changes in the document in order.


Blame, despite its negative connotation, is a very useful too for seeing the history of a document. Selecting Options > Show …blame for this file renders a page that assigns a commit number, timestamp, author, and color code for each to go with each line of the file. This helps to determine the relative “age” of a line in a file, as well as who made the change.

To demonstrate, you can see the blame display for this HELP file.

Other Features

Other features that may be useful to you.

RSS Feeds



It shows each commit as a single RSS entry.


Giterary allows for a fairly basic form of “templating,” by allowing one document to be used as the basis for a creation of another. This is useful for quickly creating a number of documents with similar content.

On any document, you can choose from the “Other Options” drop down the “Use this as a template” item. This wil allow you to use the source page as the initial contents of a chosen target page.



…will render as the following:

This allows the user to enter in the target for the template’s contents without being forced to navigate to the template each time.

Relative time display

Often it’s less important knowing the date something happened, and more important to know something’s relative age.


  • +11min means something happened between 11 and 12 minutes ago (as of last page refresh)
  • +2H means something happened between 2 and 3 hours ago.
  • +4M means something happened between 4 and 5 months ago.

In most places, if the date isn’t already displayed, a mouseover tooltip is provided to show the actual date used for the relative time.


While there are numerous ways to use Giterary as a journal, or to quickly find a place to write quick notes, there is one way which was implemented to make such things a little less tedious. The “Jot” navigation hyperlink (presented when logged in) will immediately drop you into the editing interface of a file with a naming convention that is convenient for keeping time-based data. For instance, if the date is January 21st, 2013, hitting “Jot” on this date will drop you into an editor for the file:



You can generate your own “jot” links with the jot functional link syntax. For instance:

[[jot:file=yourusername/jot|My Jot]]

…will generate the same “jot” link as is provided by the navigation “Jot” link. The file parameter is optional, and can be used to determine the prefix under which the jot file will be targeted. In this case, we want to create our files under yourusername/jot

My Jot

You can also modify the formats used by the jot function by specifying the format you would like to use for the path elements. For instance, if you wanted to explicitly define the same format as is used in the navigational “Jot” link, you can specify the format like so:


For each format parameter, the jot functional link syntax will generate a new path element.


The “%_” parameters used in the format are those used in PHP’s strftime function. Any format available to that function will be available as a path element on the jot functional link syntax.



…which will render like so:

Next Journal Entry with Pre-populated Content





You can perform a search for a character’s name, but that isn’t always ideal (what if your character doesn’t have a name?). You can try to reorganize your folder structures, but this becomes unwieldy, and can cause a lot of extra work if you end up needing to organize again, or organize in multiple ways depending on what you’re looking for.

To address this, Giterary has the concept of “tags,” which are the rough equivalent of “categories” in other wiki software. You can tag a document by entering a “~” (a tilde) at the beginning of a line, followed by a word (no spaces). A document can have as many tags as you like. For example:

Lorum ipsum, etc. Blah, blah


This makes this document appear when searching for tags “scene,” “character_name,” or “angry.”



[[tags:tag=scene|All Scenes]]

Would render to something like:

All Scenes

Note that you can “combine” tags, such that documents returned by the search have to contain all of the tags you specify (not just one). For instance:


…will search for all documents that have both the tag for authorbias and the tag for the fireflyreferences:

All docs referencing Firefly, with Author Bias


Some potential uses for tagging include:

  • Tagging scenes/chapters with the characters involved
  • Showing which documents refer to a particular plot thread, foreshadowing, or later reveal.
  • Organizing scenes/chapters by their setting ("The Battle Room,” “At the office")

TODO and TBD searching

Sometimes it is daunting to approach a document or a series of documents all at once. Case in point: Giterary’s help documentation. When writing the documentation you will think of things that need to be written, but aren’t part of your focus at the immediate moment. Switching gears will make you lose your train of thought, but it might slip your mind if you ignore it for too long.

This is where “TODO” patterns are useful. When logged in, you can visit the TODO link next to the “Jot” link in the navigation next to the search bar. This displays all lines in documents that contain either “TODO” or “TBD".

These lines can serve as anchors for later work. You can also use them to describe the basic intent of a section, and then work through your “TODOs” as time allows. As you eliminate the items in your TODO list, you get closer to completing your work.

It should be noted, though, that plain TODO listings will display in the document rendering.