mockdown -- A Markdown-inspired mockup tool
THIS PROJECT IS IN PLANNING RIGHT NOW.
Mockdown is a language for quickly creating mockups using a text editor. Mockups can be exported to a variety of formats and mockdown definition files are plain text so they work well with version control systems.
To install mockdown, simply install the gem:
$ [sudo] gem install mockdown
This will install the command line tool,
mockdown, which you can use to
export your mockups into a visual format such as HTML or PNG.
Next create a new project folder and change directories into it:
$ mockdown init my_proj $ cd my_proj
Once in your project folder, create a new file called
home.mkd with the
%page # Acme Inc %row %link label="Home" %link label="About" %link label="Contact Us" Welcome to the Acme web site! We're excited to have you here! Please look around.
Save the file and then run mockdown on your file:
You should then see a
home.png file in your directory. Open it to see your
The mockdown language is a cross between (HAML)[http://haml-lang.com] and (Markdown)[http://daringfireball.net/projects/markdown]. These two langauges were used because they're known for their ease of use and readability.
Mockdown files (*.mkd) are structured hierarchically using tags. Markdown can
be placed inside tags. Tags are created using the
Tags are a single word followed by properties which are a comma-delimited list of key-value pairs. For example, this is a tag for a button:
%button width=100, label="Click Me!"
Property values do not need to be wrapped in double quotes unless the value contains a space, comma or a double quote. Double quotes inside a value can be escaped with a backspace character.
White Space Aware
Mockdown is a white space aware language. That means that tags that are indented are nested within the previous tag that had a smaller indentation.
For example, in this mockdown example the
button is inside the
is inside the
col. However, the
checkbox is inside the
col since it is
indented the same as the
%col %row %button label="Click me" %checkbox selected=true
The following properties are available to all tags:
top- The number of pixels to position the top of the tag from the top of its parent tag.
bottom- The number of pixels to position the bottom of the tag from the bottom of its parent tag.
left- The number of pixels to position the left of the tag from the left of its parent tag.
right- The number of pixels to position the right of the tag from the right of its parent tag.
width- The width of the tag in pixels. This can be determined automatically if the
rightproperties are set. This can be set as a percentage by appending the percent sign to the value.
height- The height of the tag in pixels. This can be determined automatically if the
bottomproperties are set.
link- Links to another document. See the Links section below.
These tags can hold other tags inside of them. They are used for laying out your mockup.
col- A box that contains elements that are vertically aligned.
row- A box that contains elements that are horizontally aligned.
canvas- An area that allows for elements to be positioned using
These tags are drawing primitives designed to perform basic styling of your mockup.
line- Draws a line.
circle- Draws a circle.
rect- Draws a rectangle.
poly- Draws a polygon. This tag must contain 3 or more
point- Specifies points in a polygon.
image- Draws an image.
Drawing tags have the following properties available:
fill-color- The fill color for the shape.
fill-alpha- The opacity of the fill of shape. Value is between 0 and 100.
stroke-color- The stroke color for the shape.
stroke-alpha- The opacity of the stroke of the shape. Value is between 0 and 100.
stroke-thickness- The thickness of the stroke in pixels.
stroke-pattern- The style of stroke to use. (solid, dashed, dotted)
border-radius- The amount to curve the corners of the shape. This is only available on the
rect. Individual corners can be curved using
border-radius-and then appending
brto specify the corner.
Tags can be reused within a project or they can be packaged and distributed as libraries. To create a custom tag, simply refer to the filename (without the extension) when using the tag. If a tag is in a subdirectory, directory names can be separated by a colon.
For example, consider the following file structure for a project:
+ my_project/ + splash.mkd + home.mkd + big_button.mkd + misc/ + little_button.mkd
home.mkd file, you can use
little_button as tags:
# Acme Corp! Welcome to the Acme Corp website! %big_button label="Order Now!" %misc:little_button label="Cancel Order"
In this example, the
misc/little_button.mkd will be
embedded in the
Custom tags are searched for first in the current directory and then are
searched for in the
tags directory in the root of the project.
Mockups for various devices and platforms means that no one set of controls is enough to effectively mockup everything. Because of this, tag libraries can be built and distributed as Ruby gems.
To install a library, use the
gem command from the command line:
$ [sudo] gem install mockdown-iphone
This will install the
mockdown-iphone library. To use the library, you need
to import it into your mockdown document like this:
This will allow you to use any of the tags defined in the
Full Markdown capabilities are allowed within a Mockdown document with a few exceptions:
- Code blocks
- Inline HTML
Because Mockdown is meant for quick, simple mockups these two restrictions are typically not a problem.
Any tag can link to another mockdown document by using the
link property of
the tag. Tags will goto the specified document when clicked. Documents can be
referenced using a relative or absolute path. The file extension should be
omitted. Directories should be delimited with a forward slash.
For example, these two buttons will link to two different documents using relative and absolute paths:
%button label="View Products", link="../products/view" %button label="Home" link="/home"
If you'd like to contribute to Mockdown, start by forking the repository on GitHub:
Then follow these steps to send your
- Clone down your fork
- Create a topic branch to contain your change
- All code must have MiniTest::Unit test coverage.
- If you are adding new functionality, document it in the README
- If necessary, rebase your commits into logical chunks, without errors
- Push the branch up to GitHub
- Send me a pull request for your branch