Style Guide

Below are examples of nearly all the available syntax using Markdown, the table-of-contents , etc.

Stylistic Conventions

There are various stylistic “voices” that can be used when authoring content for this site. Depending on your audience and the context - writing a guide is different from writing a new feature entry - you might employ different “voices,” conventions, different outlines, and even different exercises to get you started.

New Features: The Elevator Pitch

Bob says
“You have only a few seconds to capture the attention of a Rhino user, potential user, or boss that knows nothing about a new Rhino feature. In those few seconds she should understand what the feature is, who it’s for, how she might benefit, and how the new feature is different from an earlier version. Before you start creating What/Why content, do this. It will save you from redoing your content many times.”

Before doing a video, forum post, blog post, or any new feature content, write down the answers to these simple questions: If you can’t answer them, don’t start creating content. Ask for help!

  • Who is the new feature targeted at? Of course many potential users can benefit. But who is ideal? Be specific.
  • Why do they want it? What compelling need does the feature satisfy? While there may be many needs, pick the one or two really compelling reasons customers will use the feature. What pain will the new feature make go away? What is a day in their life like both without and with the feature?
  • What is the feature’s category (modeling, editing, rendering, export, etc.)?
  • What is the key differentiator? Just pick the ONE that is most likely to keep someone’s attention.
  • What was the alternative before this feature was available? This doesn’t necessarily mean another vendor’s product. It could be a more painful Rhino workflow.
  • How is the new feature different from the alternative?

Armed with the answers, build an outline by filling in the following template to form a single paragraph:

For [ideal user]

who has [problem]

is a [category]

that [differentiator].

Unlike [fill in the competitor]

[fill in the key differentiator]

Get Feedback
Before you start creating content, have someone review your elevator pitch. It will save you from redoing your content many times.

Technical Conventions

Site file naming

The naming convention for files - guides, samples, etc - is lowercase with - used as spaces. This leads to more consistent and legible URLs. In addition, Google recommends one construct compound URL names with - and not underbars (_). For example, consider the name of this guide: “Style Guide”. The file name for this guide is style-guide. Google treats a hyphen as a word separator, but does not treat an underscore that way. Google treats and underscore as a word joiner — so “red_sneakers” is the same as “redsneakers.”

In general, when considering new file names for guides, please imagine you are saying “Guide to _____”. This often leads to verbs ending in “-ing”, the progressive or continuous verb tense. Obviously, this is not a hard-and-fast rule, but rather a convention.

In general, when considering new file names for samples, please imagine you are saying “_____ sample”. As with guides, this is not a hard-and-fast rule, but rather a general convention.

Division of content

# Title become H1 headers and are reserved for the title of the page only.

## Header become H2 headers and are reserved for major sections within the page.

### Sub Header become H3 headers and are reserved for sub-sections within a major section.

Fonts

OUT OF DATE
This fonts section needs to be updated.

On Windows, this site attempts to use Segoe UI (font size: 16 px, font weight: 400, line height: 1.6) and falls back to Frutiger Linotype, Dejavu Sans, Helvetica Neue, Helvetica, Arial, in that order. On macOS, the site will (almost) certainly use Helvetica Neue or Helvetica (font size: 16 px, font weight: 300, line height: 1.6). The operating system-specific font weight is set in the footer using javascript.

Paths & Filenames

*Italics* are used to denote filenames, paths, and file extensions. For example:

Navigate to C:\Program Files\Rhinoceros 5 (64-bit)\Plug-ins.

Bold

**Bold** (strong emphasis) is used in instructions to highlight critical instructions that are very important. Bold should be used sparingly as it is often present in headers as natural division of content.

Spelling & Case

The following spelling and case conventions are adopted on this site:

  • “Plugins” is not hyphenated unless it refers to a place in the Rhino UI where it is hyphenated.
  • “openNURBS” (not OpenNURBS, nor opennurbs, nor oPeNnURBs) unless it refers to a namespace in code where it is capitalized, or a path where it is not.

Images & Screenshots

Please use image names without spaces (use a hypen - NOT an underscore - for word separation). It is also safest to use lowercase filenames and extensions.

When feasible, it is best to use the .svg vector format for images, especially for diagrams.

When using bitmap images, the preferred format is .png, but any browser-friendly bitmap format will work.

When capturing screenshots, consider that many people have high-DPI (aka: “Retina”) displays. Please capture all screenshots on a high-DPI display.

See the Text Modifiers > Images section of this guide for more information on inserting images.

Headers

Headers demarcate major sections of the page, guide, etc.

Headers are created like this:

## Headers

The example above is an H2 header.

Creating a header automatically creates an #anchor tag in the generated html.

For headers with multiple words, the markdown parser lowercases all the words and adds dashes for spaces. For example, if we had a header like this:

## This Is My Header

the resulting html anchor tag would be:

#this-is-my-header

Sub Headers

Sub Headers demarcate sub-sections a major section underneath a header.

Sub Headers are created like this:

### Sub Header

The example above is an H3 header, which we are calling a “Sub Header.”

Just like with H3 headers, H3 headers also create an #anchor tag in the generated html.

Table of Contents

The UI-widget to the left of this column is a the Table of Contents (TOC) for this page. If you are authoring a page that requires a TOC, you can generate one automatically by setting the Page Options > TOC to enabled (page_options: toc: true).

For example, to get the main title to show up in the TOC, you would type this:

# The Title

To get a Header to show up in the TOC, you would type this:

## Cool Header

To get a Sub Header to show up in the TOC, you would type this:

### Sweet Sub Header

Note: TOCs are only generated from H1, H2, and H3 headers…H4 (and smaller) headers are ignored by the TOC-enabled pages.

Structural Elements

Paragraphs

Consecutive lines of text are considered to be one paragraph. You must add a blank line between paragraphs.

Block Quotes

A blockquote is started using the > marker followed by an optional space; all following lines that are also started with the blockquote marker belong to the blockquote. You can use any block-level elements inside a blockquote:

> This is a sample block quote
>
> >Nested blockquotes are also possible.

Yields:

This is a sample block quote

Nested blockquotes are also possible.

Code Blocks

To create a code block, surround the code with three back-ticks, followed by a language abbreviation. For example:

```

…followed by the code…

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
public static Rhino.Commands.Result AddCircle(Rhino.RhinoDoc doc)
{
  Rhino.Geometry.Point3d center = new Rhino.Geometry.Point3d(0, 0, 0);
  const double radius = 10.0;
  Rhino.Geometry.Circle c = new Rhino.Geometry.Circle(center, radius);
  if (doc.Objects.AddCircle(c) != Guid.Empty)
  {
    doc.Views.Redraw();
    return Rhino.Commands.Result.Success;
  }
  return Rhino.Commands.Result.Failure;
}

…and finally closed by three back-ticks.

The abbreviation after the first set of back-ticks is the language code for syntax highlighting. We are using a syntax highlighting built into Go’s Chroma Highlighting engine. Many languages are supported. The most common language abbreviations used on this site are:

  • cs is C#
  • vbnet is Visual Basic
  • python is Python
  • cpp is C/C++

A complete list of language aliases can be found in the List of Chroma Highlighting Languages.

Horizontal Rules

Horizontal rules (lines) are created by using three dashes:

---

You can an example of one of these right here…


Lists

You can create ordered lists and unordered lists.

Ordered Lists

Ordered lists are created by typing 1. at the start of a line, like this:

This is an ordered list:

1. Item one.
1. Item two.
1. Item three.

yields:

This is an ordered list:

  1. Item one.
  2. Item two.
  3. Item three.

Nested ordered lists are also possible. For example:

This is a nested ordered list:

1. Do item one.
   1. Item one subtask one.
   1. Item one subtask two.
1. Do item two.
1. Do item three.

yields:

This is a nested ordered list:

  1. Do item one.
    1. Item one subtask one.
    2. Item one subtask two.
  2. Do item two.
  3. Do item three.

Unordered Lists

Unordered lists (bullet lists) are created using the dash (-) symbol at the beginning of a line:

This is a bullet list:

* Item one
* Item two
* Item three

yields:

This is a bullet list:

  • Item one
  • Item two
  • Item three

Tables

markdown supports a syntax for creating simple tables. A line starting with a pipe character starts a table row. However, if the pipe characters is immediately followed by a dash (-), a separator line is created. Separator lines are used to split the table header from the table body (and optionally align the table columns) and to split the table body into multiple parts. If the pipe character is followed by an equal sign (=), the tables rows below it are part of the table footer.

Here is the syntax for a simple table:

| Header1 | Header2 | Header3 |
|:--------|:-------:|--------:|
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
| cell7   | cell8   | cell9   |

yields:

Header1 Header2 Header3
cell1 cell2 cell3
cell4 cell5 cell6
cell7 cell8 cell9

HTML Elements

markdown allows you to use block-level HTML tags (div, p, pre, etc) to markup whole blocks of text – just start a line with a block-level HTML tag.

Please use HTML sparingly
Scattering html all over the markdown results in ugly, difficult to maintain, and not-very-portable markdown content. Please using sparingly. If you find yourself needing something more elaborate, please ask for a custom shortcode.

Here is an example of using HTML elements:

<div style="float: right">
Something that stays right and is not wrapped in a para.
</div>

<div>
This is wrapped in a para.
</div>
<p>
This can contain only *span* level elements.
</p>

yields:

Something that stays right and is not wrapped in a para.
This is wrapped in a para.

This can contain only *span* level elements.

Text Modifiers

Emphasis

Emphasis (bold and italic) can be added to text by surrounding the text with asterisks:

For example:

I like *my* coffee **bold**.

yields:

I like my coffee bold.

Simple Links

A simple link can be created by surrounding the text with square brackets and the link URL with parentheses:

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

yields:

This is a link to the Rhino 3D homepage.

You can also add title information to the link:

A [link](https://www.rhino3d.com "Rhino 3D homepage") to the homepage.

yields:

A link to the homepage.

There is another way to create links which does not interrupt the text flow. The URL and title are defined using a reference name and this reference name is then used in square brackets instead of the link URL:

A [link][rhino3d homepage] to the homepage.

[rhino3d homepage]: https://www.rhino3d.com "Modeling tools for designers"

yields:

A link to the homepage.

If the link text itself is the reference name, the second set of square brackets can be omitted:

A link to the [Rhino3D homepage].

[Rhino3D homepage]: https://www.rhino3d.com "Modeling tools for designers"

yields:

A link to the Rhino3D homepage.

Anchor Links

As discussed above, Headers and Sub Headers automatically create anchors in the resulting rendered html output.

You can link to any anchor within a page using the hash # symbol in a normal link. For example:

[Sub Headers](#sub-headers) automatically create anchors in the resulting rendered html output

yields the sentence fragment shown above.

To create new anchors within the site, you can use html inline. For example:

<a id="top"></a>

was added to the top of this page.

Internal Links

If you’re linking to another part of this site, you can use relative links from the root of the site. For example:

[How This Site Works](/admin/how-this-site-works/)

Inline Code

Text phrases can be easily marked up as code by surrounding them with back-ticks:

To write a line to the command line use the `Rhino.RhinoApp.WriteLine` method.

yields:

To write a line to the command line use the Rhino.RhinoApp.WriteLine method.

HTML Elements

HTML is not only supported on the block-level but also on the span-level:

This is <span style="color: red">written in red</span>.

yields:

This is written in red.

MathJax & LaTeX

markdown has support for LaTeX to PNG rendering via MathJax.

For example:

$$y = {\sqrt{x^2+(x-1)} \over x-3} + \left| 2x \over x^{0.5x} \right|$$

yields:

$$y = {\sqrt{x^2+(x-1)} \over x-3} + \left| 2x \over x^{0.5x} \right|$$

See the MathJax basic tutorial and quick reference on StackExchange.

Images

Images can be created in a similar way to links: just use an exclamation mark before the square brackets. The link text will become the alternative text of the image and the link URL specifies the image source:

![computelogo](/images/rhino_compute_logo.png)

yields:

computelogo

Image Names
Please use image names without spaces (use a hypen - NOT an underscore - for word separation). It is also safest to use lowercase filenames and extensions.

Shortcodes

Shortcodes are Hugo’s way of inserting a html into your content that generate some special type of formatted output. Hugo comes with some built-in shortcodes for things like inserting Vimeo or YouTube videos, Instagram or Twitter posts, etc. but we can author our own shortcodes to suit our needs.

Common Shortcode Mistakes
  • Shortcodes are very picky about formatting: even the slightest missing brace can cause the site not to deploy. Don’t worry, you won’t break the site, you just won’t see your change go live until it is fixed.
  • Shortcodes only work when used in the content of a post, not in the frontmatter. You may be tempted to use them in the frontmatter, but they don’t work there.
  • If you are referencing images, pease make sure to only use files with lowercase names and NO SPACES!

So far, we’ve got the following shortcodes of our own:

Awesome (Font Awesome)

Font Awesome provides a huge library of vector icons that area easy to use with this sortcode:

{{< awesome fas fa-check small >}} produces:

You can also specify a size and a color like this:

{{< awesome id="fab fa-windows" size="small" color="#49abe9" >}} produces:

BeforeAfter

You can create image-based before-and-after comparisons with the following shortcode:

{{< beforeafter "/images/before.png" "/images/after.png" >}}

produces:

Before After

You can also supply optional captions for the left and right images like this:

{{< beforeafter "/images/before.png" "/images/after.png" "This text at left" "This text at right" >}}

This shortcode uses the twentytwenty jQuery widget.

Call-Out

To call attention to a specific area of content on the page, use the call-out shortcode.

For example:

{{< call-out danger "Here Be Dragons" >}}
Don't click that button man...it's dangerous dude.
{{< /call-out >}}

produces:

Here Be Dragons
Don’t click that button man…it’s dangerous dude.

The following arguments can be passed to the shortcode to determine the type:

  • note
  • abstract
  • info
  • tip
  • success
  • question
  • warning
  • failure
  • danger
  • bug
  • example
  • quote

Align

{{< align left >}}Left Wing{{< /align >}}
{{< align center >}}Centrist{{< /align >}}
{{< align right >}}Right Wing{{< /align >}}

produces

Left Wing
Centrist
Right Wing

Center

Use the center shortcode to center images, text, etc. in the div.

For example:

{{< center >}}
This text is centered
{{< /center >}}

produces:

This text is centered

You can center images too using the image argument like this:

{{< center image >}}
![This image is centered](logo.png)
{{< /center >}}

produces

This image is centered

Command

TODO
This shortcode is not yet documented because we have not yet ported the commands over to the new website

Command What’s New

TODO
This shortcode is not yet documented because we have not yet ported the commands over to the new website

Figure

Use the figure shortcode to insert images with captions like this:

{{< figure src="/images/light-falloff-after.png" caption="Lights have a falloff value that can be set to inverse squared which mimics how light fades with distance." >}}

produces:

Lights have a falloff value that can be set to inverse squared which mimics how light fades with distance.

Lights have a falloff value that can be set to inverse squared which mimics how light fades with distance.

Optionally, you can also use the gallery and load-photoswipe shortcodes to embed figures in a gallery and pop-up an image overlay when users click or tap on the image.

The gallery shortcode used to show multiple images in a thumbnail grid. It is used in conjuction with the figure and load-photoswipe shortcodes like this:

{{< gallery >}}
  {{< figure src="/images/quadremesh-thumbnail.png" caption="Horse mesh retopologized" >}}
  {{< figure src="/images/pbr_material.png" caption="A PBR Material" >}}
  {{< figure src="/images/project.jpg" caption="Look! A toaster!" >}}  
{{< /gallery >}}
{{< load-photoswipe >}}

produces:

This shortcode uses the hugo-easy-gallery shortcode, along with Photoswipe.

Image Processing (imgproc)

Hugo comes with a number of useful image processing routines like resizing and cropping. It’s important to understand that these are not just css styles, but actual processes the generate entirely new derivative files based on the image you use as your input. This is especially useful for generating thumbnails from large images so that a smaller (in kb) image is delivered in those situations where a larger one would cause slow pageloads. Think of these image processing routines as the equivalent of opening up your file in a program like Photoshop and performing resizing, format, or cropping operations on them.

This only works on page-bundle images
Currently, this shortcode only works on page-bundle images and not on images in the static folder (the main images folder). You will have to use GitHub to upload these into the proper spot.

To use the Image Processing routines on the page, use the imgproc shortcode.

Here is an example that resizes an image:

{{< imgproc "logo.png" "Resize" "48x48" >}}

Make sure you close the final brace (not shown above, unfortunately) with a forward slash / like this…

/>}}

produces

Latest Rhino Version

Avoid writing the latest Rhino version in text. Instead, the site itself knows which is the current shipping version. So use the following shortcode:

{{< latest-rhino-version >}} produces 7

Load Photoswipe

The load-photoswipe shortcode loads the javascript libraries on this page in order to support clicking or tapping on an image to show a lightbox-style image overlay. You only need to call it once per page like this:

{{< load-photoswipe >}}

and the library will load.

New Label

Use the New Label along with the included_in.since frontmatter field to create version-specific “new” labels.

Standard size:

{{< new-label 6 >}} produces:

Small size:

An inline {{< new-label 6 small >}} small new label produces:

An inline

small new label. There’s a bug here that causes a line-wrap in the middle. Brian doesn’t know how to fix it.

Bullet in list:

  * {{< new-label 6 bullet >}} Feature description
  * A feature from a previous version
  * {{< new-label 7 bullet >}} A feature from a previous version

produces:

  • Feature description
  • A feature from a previous version
  • A feature from a previous version

Open Rhino

To open URL in Rhino, use the:

{{< open-rhino 
    "https://docs.mcneel.com/rhino/6/training-command/en-us/samples/Clip.3dm"
    "Open Clip.3dm in Rhino"
     />}}

to produce:

Open Clip.3dm in Rhino

To open Rhino by clicking an image:

{{< open-rhino "https://docs.mcneel.com/rhino/6/training-command/en-us/samples/Clip.3dm" >}}
![computelogo](/images/rhino_compute_logo.png)
{{< /open-rhino >}}
computelogo

Rhino Download

To produce a link to a Rhino download page, use the:

  * {{< rhino-download >}}
  * {{< rhino-download 7 windows evaluation >}}
  * {{< rhino-download 7 windows commercial >}}
  * {{< rhino-download evaluation >}}
  * {{< rhino-download commercial >}}

to produce:

The acceptable arguments are:

  1. version eg: 7, 8 (major versions only)
  2. platform eg: windows or mac
  3. type eg: beta, wip, or commercial.

Without any arguments, a link to the latest commercial version on each platform is produced:

{{< rhino-download >}}

results in :

Row and Column

Use the {{< row >}} and {{< column >}} shortcodes together to create responsive flow layouts like this:

{{< row >}}
{{< column >}}
Row 1: Column 1
{{< /column >}}
{{< column >}}
Row 1: Column 2
{{< /column >}}
{{< column >}}
Row 1: Column 3
{{< /column >}}
{{< /row >}}
{{< row >}}
{{< column >}}
Row 2: Column 1
{{< /column >}}
{{< column >}}
Row 2: Column 2
{{< /column >}}
{{< column >}}
Row 2: Column 3
{{< /column >}}
{{< /row >}}
{{< row >}}
{{< column >}}
Row 3: Column 1
{{< /column >}}
{{< column >}}
Row 3: Column 2
{{< /column >}}
{{< column >}}
Row 3: Column 3
{{< /column >}}
{{< /row >}}

produces:

Row 1: Column 1
Row 1: Column 2
Row 1: Column 3
Row 2: Column 1
Row 2: Column 2
Row 2: Column 3
Row 3: Column 1
Row 3: Column 2
Row 3: Column 3

Vimeo and YouTube Videos

Vimeo

We have extended the built-in vimeo shortcode to support Autoplay and looping…

For example:

{{< vimeo id="447325407" autoplay="1" loop="1" autopause="0" >}}

produces:

YouTube

Hugo has a built-in youtube shortcode that can be used to embed videos like this:

{{< youtube TeTiZuSbQz8 >}}

produces:

What’s New

TODO
The What’s New shortcode is not yet documented and may be rolled-into the command shortcode.

Use: {{< wikipedia-link Cosmic_latte >}} to get: ikipedia: Cosmic latte