On this page

Tip

To see the raw markup for any page in the help server, visit the URL with .txt on the end, for example /nodes/sop/copy.txt.

Quick start

Page structure

= Title =

#name: value

"""Summary."""

== First heading ==

This is a paragraph.

Separate paragraphs with a blank line.

== Second heading ==

* Bullet one.

* Bullet two

    Sub-paragraph of bullet two.

Styles

This is *bold*, this is _italics_, this is `code`, 

Comments

// Single line comment

<!--
HTML-style freeform comment
-->

Title

Title

= Title =

Pre and subtitles

Titles can have “pre-title” and/or “sub-title” parts that are visually de-emphasized in the HTML.

Title with pre-title

= What's new |> Rendering =

Title with sub-title

= Saturday the 14th <| the sequel =

Both pre-title and sub-title

= Pre-title |> Main title <| Sub-title =

Properties

Markup

Properties are used extensively to modify the rendering of blocks. The basic form of a property is:

#name: value

Page properties

Properties that come before any headings apply to the whole page.

= Title =

#context: sop
#internal: copy

See the list of page properties below.

Block properties

Properties indented under a block apply to that block.

* This is a bullet point.
    #name: value

See individual block types below for lists of the available properties for each one.

Multi-line

You can have multi-line values by indenting the value.

#name:
    This is a multi-line
    property value.

List of page properties

Name

Value

#icon: ‹path

Path to a small image to represent this page.

#display:

A space-separated list of display classes to apply to the page.

notitle

Don’t show the page title.

See display property for more. This feature is experimental and subject to change.

#redirect: ‹path

When the help system goes to load this page, redirect it to the given path.

#parent: ‹path

See parents and subtopics.

Headings

Markup

== Heading level 2 ==

=== Heading level 3 ===

==== Heading level 4 ===

ID

You can give a heading an ID using a standard property:

== How to ==
#id: howto

This allows you to link to the heading (see linking below). There is also a slightly more compact markup available for associating an ID with a heading:

== How to == (howto)

Indentation

Usually in this wiki markup, indentation indicates that indented blocks are “inside” the blocks they're indented under. However, it’s not necessary to indent under headings. The parser will automatically “do the right thing” and add any blocks — and any subordinate headings — after a heading to that heading.

For example:

== Foo ==

This paragraph will be considered part
of the "Foo" section, even though it's not
indented under it.

=== Bar ===

This block is under the "Bar" heading, which
is under the "Foo" heading.

You only need to indent under a heading if you want some following paragraphs to be under the heading, but not all. This sometimes comes up when including content:

== Heading to include == (includeme)

    I want this paragraph to be included with the heading when I include it from another page.

I don't want this paragraph to be included.

Display properties

pull left

Indent the content and show the heading in the left margin.

notitle

Don’t show the heading.

Lists

Bullet lists

* Bullet
* Bullet

Numbered lists

# First
# Second

Definitions

Cat:
    A type of animal.

Cinq:
    French word for five.

Tasks

:task: Start a render:
    # Go to the Render view tab.
    # Click __Render__.

:task: Quit using Houdini:
    Rethink your life choices.

Text

Styles

Markup

Rendering

*Bold*

Bold

_Italics_

Italics

`Code`

Code

__UI__

UI

__File > Open__

File ▸ Open

<<variable>>

variable

Keys

Markup

Rendering

((K))

K

((Shift))

⇧ Shift

((Shift + K))

⇧ Shift + K

((Alt)) ((Option))

Alt ⌥ Option

((Ctrl)) ((Cmd))

⌃ Ctrl

((Up)) ((Down)) ((Left)) ((Right))

((Tab))

⇥ Tab

((Del))

⌦ Del

((mouse))

((LMB)) ((MMB)) ((RMB))

((mouse_wheel))

Typography

Markup

Replacement

Apostrophes and quotes

Curly quotes

<- and ->

← and →

4x4

4×4

<= and =>

≤ and ≥

(c) (tm) (r)

© ™ ®

...

Notices

Tips and notes

Markup
Rendering
TIP:
    This is a tip.

    This is the second paragraph of the tip

NOTE:
    This is a note.

WARNING:
    This is something you shouldn't do.

Tip

This is a tip.

This is the second paragraph of the tip.

Note

This is a note.

Warning

This is something you shouldn’t do.

The capitalized TIP: syntax is meant to be visually noticeable for writers in a page of markup. It is equivalent to the following more standard markup:

Standard item forms

:tip:
    This is a tip

:note:
    This is a note.

:warning:
    This is a warning.

Other notices

Houdini includes a few other types of notices. You can only use the standard item markup for these, they don’t have captialized equivalents.

Markup
Rendering
:new:
    Something new.

:improved:
    Something got faster.

:changed:
    Something changed.

:dev:
    Something for developers

:fixed:
    Something was fixed.

:bug:
    Something isn't fixed yet.

New

Something new.

Improved

Something got faster.

Changed

Something changed.

Developer

Something for developers

Fixed

Something was fixed.

Unresolved

Something isn’t fixed yet.

Platform

There is a special notice for specifying things that are different on Mac OS X, Windows, and Linux.

Markup
Rendering
:platform:Mac
    This is what's up on Mac.

:platform:Windows
    This is the 411 on Windows.

:platform:Linux
    This is what's going down on Linux.

Mac

This is what’s up on Mac.

Windows

This is the 411 on Windows.

Linux

This is what’s going down on Linux.

Icons

Icons

Markup

Rendering

[Smallicon:SOP/copy]

[Icon:SOP/copy]

[Largeicon:SOP/copy]

Font Awesome

You can also use icons from the Font Awesome 4 icon font in your pages.

Headings, bullets, definitions, notices, table cells, and tabs can have custom glyphs using the #glyph: property.

Markup
Rendering
* Remember to bring a brolly.
    #glyph: fa-umbrella

* Go to the office.
    #glyph: fa-building

* Pick up empty boxes.
    #glyph: fa-cube

TIP:
    #glyph: fa-certificate

    This is a new feature.
  • Remember to bring a brolly.

  • Go to the office.

  • Pick up empty boxes.

Tip

This is a new feature.

You can embed a Font Awesome glyph in text:

Markup

Rendering

+(fa-rocket)

You can use other font-awesome CSS classes in the #glyph property, such as fa-spin.

Markup
Rendering
* This will take a few seconds.
    #glyph: fa-spinner fa-spin
  • This will take a few seconds.

Tables

Simple tables

The simple table markup handles most cases.

Lines that end in a double vertical line (||) are heading cells. Lines that end in a single vertical line (|) are regular cells. Indented cells appear next to the parent.

Markup
Rendering
Column 1 ||
    Column 2 || 

First cell |
    Second cell

    Second paragraph in second cell.

Column 1

Column 2

First cell

Second cell

Second paragraph in second cell.

The main drawback of the simple markup is that only the last cell in a row can have multiple paragraphs.

Full tables

If you need a more complex table than what the simple markup can create (for example, row or columns spans), you can use an HTML table. See HTML below.

HTML

Embedding HTML

You can embed HTML in wiki markup. With the HTML tags, text is parsed as wiki text.

You need to <strike>burn</strike> deprecate that node.

Pseudo HTML

For complex HTML, it can be cleaner to use a “pseudo-HTML” markup based on indentation.

Lines ending with >> are treated as an HTML element tag, with any content indented under it treated as the HTML element content.

table width="100%">>
    tr>>
        td colspan="2">>
            Alpha
        td>>
            Bravo
    tr>>
        td>> Charlie
        td>> Delta
        td>> Echo

Organization

Dividers

A line with three or more tilde (~) characters creates a horizontal line. If you put text after the tildes it creates a labeled divider.

Markup
Markup
Line divider

~~~

Line divider with text

~~~ Or ~~~

Line with display style

~~~~
    #display: red

Easy!

Line divider

Line divider with text

OR

Line with display style

Easy!

Boxes

Markup
Rendering
:box:
    #display: raised

    This is content inside a box.

This is content inside a box.

rounded

raised

bordered

inverted

Captions

Adding text to a box block puts a small label on the content inside.

Markup
Rendering
:box: Decorator example
    {{{
    #!python
    @decorator
    def foo():
        return “bar”
    }}}

Decorator example

@decorator
def foo():
    return "bar"

Columns

Columns adapt to the browser width. They will collapse into a single column when their container is narrow.

Markup
Rendering
:col:
    Column 1 paragraph 1

    Column 1 paragraph 2

:col:
    Column 2 paragraph 1

    Column 2 paragraph 2

Column 1 paragraph 1

Column 1 paragraph 2

Column 2 paragraph 1

Column 2 paragraph 2

(If you don’t see columns above, try widening your browser window.)

Tabs

Markup
Rendering
:tab: Reality
    This is the real world.

:tab: Fantasy
    This is the imaginary world.
Reality
Fantasy

This is the real world.

This is the imaginary world.

#selected: true

Add this property to a tab to make it selected when the page loads.

#glyph: ‹font-awesome-name

Add this property to display a Font Awesome glyph in a tab.

Dividing blocks

If you use only two tildes (~~) it creates an “invisible” divider. This doesn’t render as a line, but breaks up groups of blocks of the same type. This is useful for when you have a series of :tab: or :col: blocks and you want to separate them into different groups.

Four adjacent :col: blocks become a four column layout
:col:
    Far left
:col:
    Middle left
:col:
    Middle right
:col:
    Far right
Invisible divider ~~ separates adjacent blocks into two groups
:col:
    Left
:col:
    Right

~~

:col:
    Left
:col:
    Right

Bubbles

A bubble is a special box type that looks like a chat bubble.

Markup
Rendering
:bubble: He said _what_!?
    #dir: left
    #display: yellow

:bubble:
    #dir: right
    #display: teal

    I know right!?

    Where does he get the nerve?

He said what!?

I know right!?

Where does he get the nerve?

#dir: ‹direction

right

down

left

up

#display: ‹look

Use to set the color of the bubble. See display properties.

Disclosure

A :disclosure: block lets you subtly hide extra information under a collapsed heading.

Markup
Rendering
:disclosure:Technical discussion
    Overly technical explanation which most users
    won't be interested in.

Footnotes

You can hide extra text in a “footnote” called a fold. The [Fold:‹name›] shortcut creates a button. If there is a :box: with a property #fold: ‹name with the same name, clicking the button will reveal the box content.

Markup
Rendered
Everything you wanted to know about Houdini[Fold:1].

:box:
    #fold: 1

    ...but were afraid to ask

Everything you wanted to know about Houdini.

…but were afraid to ask

You can refer to the same fold box using multiple shortcuts, as long as they have the same name as the box’s #fold: property.

Code

Inline

Put text within backticks (`) to render it as code.

Type `echo $HFS` in a shell.

Code blocks

Lines between {{{ and }}} are treated as a block of code.

If the first line starts with #! it specifies the syntax coloring to use. You can use any syntax names from the Pygments library, as well as Houdini-specific languages hscript and vex.

{{{
#!python
def double(n):
    return n * 2
}}}

Display property

#display:

You can use a #display: property on the page and on various block types to modify how the block appears in HTML. The value is a space-separated list of class

== Header ==
#display: notitle collapsible inverted

:tab: Tab 1
    #display: red

    Tab content.

Note

Many possible display values don’t work on all block types, or aren’t fully implemented, or may not work in all combinations.

The following block types accept display properties in various forms:

  • Page

  • Headings

  • Columns

  • Table cells

  • Tabs

  • Dividing lines

  • Boxes

  • Bubbles

Values

notitle

For a page or heading, hides the title.

collapsible

For a heading, allows the user to collapse and expand the content.

collapsed

For a heading, start in a collapsed state.

pull ‹left|right

For a heading, moves the title beside the body.

inverted

Display the content as light-on-dark.

colorname

You can use the name of a color to colorize the block. Different block types may apply colors in different ways.

Markup
Rendered
:box:
    #display: raised yellow

    This is a raised yellow box.

TIP:
    #display: orange

    This is an orange tip.

This is a raised yellow box.

Tip

This is an orange tip.

gray

blue

pink

red

green

yellow

purple

magenta

teal

orange

seafoam

white

@-sign sections

Overview

An @-section acts like a top-level heading. It marks a particular section of a page. Items within that section may be treated specially.

For example, node help will have a “parameters” section:

@parameters

Within that section, anonymous items are treated as documenting a specific parameter:

@parameters

::Group:
    Specifies which elements this node applies to.

This will be indexed and rendered differently than if you used an anonymous item block outside the @parameters section

Markup

An @-section looks like this:

@name Title

If you don’t give a title, the heading will render using the name of the section capitalized (for example @parameters → Parameters).

Properties

#status: ‹code

  • nd – not documented

  • ni – not implemented.

You can use #display: properties on sections just like headings.

Includes

Markup

To include the content of another file (the path can be absolute or relative to the current page):

:include path/to/file:

To include only one block from another file, add a # and the ID of the block:

:include /path/to/file#blockid:

To include only the contents of one block from another file, add a trailing slash after the ID:

:include /path/to/file#blockid/:

Searches

Basics

The :list: block lets you show the results of search queries on the page.

Markup
Rendering
:list:
    #query: title:cap

Properties

#query: ‹search query

A search query.

#filtered: ‹yes|no

If no, don’t show a filtering interface above the results.

#filters: ‹field names

A space separated list of search fields to allow the user to filter the results by.

#sortedby: ‹field name

The name of a field to sort the results by. Prefix the field name with a minus sign (-) to reverse the sorting order.

#groupedby: ‹field name

Group the results by the value of the given field.

If you specify a #groupedby: field, you can also optionally specify a #labels: ‹path property. This points to an .ini file on the server with a [Labels] section that maps field values to group labels.

#includecontent: ‹true|false

If true, includes the content of each matched document under the link. This can make your page very large, so be careful.

#limit: ‹num

Limit the search results to this number of hits.

#display:

show-icons

Displays icons for the search results that have them.

narrow-columns / columns / wide-columns

Divides the results into columns.

Parents and subtopics

Index page

In a directory of wiki files, any file named index.txt is treated as the “table of contents” page for the directory. If the user browses to the directory, the server shows the index page.

Subtopics

To link to “child” topics of the current “parent” page, create a @subtopics section.

@subtopics

::[Introduction to rendering|intro]
::[Advanced rendering|advanced]

The “child” links do not need to be in the same directory as the parent.

You can use headings in the subtopics section to organize the links:

@subtopics

== Getting started ==

::[Introduction to rendering|intro]
::[Starting a basic render|basic]

== Next steps ==

::[Tuning for performance|tuning]

Parent property

Each page displays “breadcrumbs” indicating the parents of the current page in the hierarchy. If the directory a page is in has an _index page, that is automatically treated as the parent page.

If the directory doesn’t have an _index page, or you want to use a different parent, include a top-level #parent: property with the path to the parent page:

= Title =

#parent: /examples/

How to use the help

Basics

Documenting nodes

Running a central help server