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 ¶
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 |
---|---|
|
Path to a small image to represent this page. |
|
A space-separated list of display classes to apply to the page.
Don’t show the page title. See display property for more. This feature is experimental and subject to change. |
|
When the help system goes to load this page, redirect it to the given path. |
|
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 ¶
Text ¶
Styles ¶
Markup |
Rendering |
---|---|
|
Bold |
|
Italics |
|
|
|
UI |
|
File ▸ Open |
|
‹variable› |
Keys ¶
Markup |
Rendering |
---|---|
|
K |
|
⇧ Shift |
|
⇧ Shift + K |
|
Alt ⌥ Option |
|
⌃ Ctrl ⌘ |
|
↑ ↓ ← → |
|
⇥ Tab |
|
⌦ Del |
|
|
|
|
|
|
Typography ¶
Markup |
Replacement |
---|---|
Apostrophes and quotes |
Curly quotes |
|
← and → |
|
4×4 |
|
≤ and ≥ |
|
© ™ ® |
|
… |
Notices ¶
Tips and notes ¶
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.
: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.
: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 |
---|---|
|
|
|
|
|
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.
* 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 |
---|---|
|
|
You can use other font-awesome CSS classes in the #glyph
property, such as fa-spin
.
* This will take a few seconds. #glyph: fa-spinner fa-spin
-
This will take a few seconds.
Media and links ¶
Links ¶
Link to |
Markup |
---|---|
Wiki |
|
Web page |
|
Link within a page ¶
To link within a page, first give a heading or other block an ID:
== Heading to link to == (linktome)
Then to link to it on the same page:
[go there|#linktome]
or from another page:
[go there|/path/to/page#linktome]
Shortcuts ¶
Link to |
Markup |
---|---|
Node |
|
Expression function |
|
VEX function |
|
Mantra property |
|
HOM module/class |
|
HOM method/function |
|
Wikipedia |
|
HScript command |
|
Image ¶
Figure (lightbox image with optional caption) ¶
Compare images ¶
:compare_images: #image1: /images/buildings.jpg #image2: /images/commute.jpg
Video ¶
:video: #src: /path/to/video.mp4
You can optionally use #loop: true
and/or #autoplay: true
to control looping and autoplay.
Vimeo video ¶
:vimeo: Video title #id: 84058031
Charts and graphs ¶
You can generate charts and graphs on the page using the FLOT library. See that page for information on the options and data format.
:chart: #left: truth #bottom: height #options: { "xaxis": {"ticks": [0, 50, 100, 150, 180, 200, 250]}, "yaxis": {"ticks": [0, 0.5, 1]} } #data: [ {"data": [ [0, 0], [179, 0], [180, 1], [250, 1] ]} ]
left |
A label for the chart’s left (vertical) axis. |
bottom |
A label for the chart’s bottom (horizontal) axis. |
options |
A JSON object, passed to the library. |
data |
A JSON list, passed to the library. |
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.
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.
Line divider ~~~ Line divider with text ~~~ Or ~~~ Line with display style ~~~~ #display: red Easy!
Line divider
Line divider with text
Line with display style
Easy!
Boxes ¶
:box: #display: raised This is content inside a box.
This is content inside a box.
rounded
raised
bordered
inverted
Captions ¶
Columns ¶
Columns adapt to the browser width. They will collapse into a single column when their container is narrow.
: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 ¶
:tab: Reality This is the real world. :tab: Fantasy This is the imaginary world.
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.
Bubbles ¶
A bubble is a special box type that looks like a chat bubble.
: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.
:disclosure:Technical discussion Overly technical explanation which most users won't be interested in.
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.
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.
: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.
: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/