Write Up Manual

Introduction

Write Up is a documentation generator. The documentation is typed using markdown language and the output is a set of HTML documents. The output is self-contained, can be viewed using a web browser and can be structured for use online or offline.

Project

A project is the collection of properties and content that represent a single set of documentation. Projects have properties like the title or output mode and contain a sequence of pages which constitute the entire content of the documentation.

Projects can be created and modified using the set of controls exposed by the application, and only one project can be open at any time. While the project is open, it is periodically saved to the browser's local storage to prevent data loss when the application tab is closed.

Projects can also be saved to a file using the Save Project button in the toolbar and loaded again at a later stage for modification and generation.

Structure

Pages

The documentation is created as a sequence of pages, with each page having a title and a url. The title is displayed in the browser tab as well as the menu of pages that is visible on every page. The url is used to identify the page on the file system and is used differently depending on the selected output mode.

A single page can be designated as the root page by giving it the url "/". The root page is the landing page of the documentation.

Stylesheet

Each project has a CSS stylesheet that can be used to modify the appearance of the generated html. Using media queries, the stylsheet can also be used to modify the appearance of the printed output.

File Library

The file library is a list of files that are accessible to the pages of the documentation. Files are managed via the file library dialog and can be referenced in the src attribute of img, audio and video elements.

Files are referenced using the following synatx:

  <img src='@{filename.jpg}'>

Output Mode

The output determines the structure of the files that will be generated. There are two available modes: Online and Offline.

Online mode produces documentation where different pages are placed in separate directories and the url of the page is used for the directory name. The root page is placed in the root directory of all the directories.

Offline mode produces documentation where every page is placed in the same directory and the url of each one is used to name the html file that contains the page content.

Markdown

Markdown is a lightweight markup language with plain text formatting syntax. Each page is composed using Markdown text entered into the edit box in the center of the application interface and a preview of the output is displayed in the pane on the right.

Consult this guide or the original specification for details about the syntax.

Output Preview

The output preview is displayed on the rightmost panel of the application and sows what the selected page will look like when it is saved as a web page.

The headings in the preview are shown with a hash tag to the right of them. These are provided for reference and can be used to link to specific headings in the documentation pages. The tags are not actually shown in the final product.

Headings

Any headings on a page will be accessible via a menu in the generated documentation. The only exception are the topmost headings, with the tag HTML <h1>.

Page Linking

Markdown syntax provides a method for linking to other web pages or resources on the internet using urls. Example:

This is a [link](https://www.example.com).

That would show up in the final product as:

This is a link.

When linking to pages of the project itself, it is useful to be able to refer to specific pages using a syntax that will create a valid link regardless of the eventual output mode that is used. This can be done using the following syntax:

This is a [link](${The-Page-Url}#a-heading-on-the-page).

This will always produce a valid link to the correct page, and section of the page, as long as the correct url and tag are used.

This syntax will also be processed correctly when used in anchor links within inline HTML.

Output

The final output is produced by clicking the Generate Documentation button in the toolbar. A file name can be entered for the package and it will then be downloaded as a zip file.