by Dan Rigdon-Bel (Last updated: Monday, October 7, 2024)

Every time a commit is pushed to this git repository’s main branch, a static site-generator called Hugo churns through all the markdown content to generate html for the site.

Workflow

The best way to understand how this site works is to make a change to it. Follow these steps:

1. If you have not already, read the README’s Getting Started section. This will get you setup building the entire site locally on your computer so you can preview changes before making them live (by committing and pushing).
2. With the site up and running on your localhost, make a change to one of the pages (find a typo…there are many). A good editor for Markdown is the Visual Studio Code. Once you save your changes to the .md file, Hugo will automatically refresh the page with your changes.
3. If you are satisfied with your change, use git to commit your change to the GitHub repository (or submit a pull-request for review).
4. Wait a minute or two (If you issued a pull-request, your change won’t be live until a git administrator accepts it).
5. On the live developer.rhino3d.com, you should see your change.

Frontmatter

The top of each file in the /contents/en folder - “content” for short - contains metadata called “frontmatter.” This frontmatter is in the toml format between the first +++ and the second +++. For example, this guide’s source has:

This toml metadata determines how this piece of content is organized and presented in lists. Hugo has some default frontmatter entries (like title = "Something something"), but the key/value pairs can be customized to our liking. This frontmatter is used - at the time the site is built - to determine how the page renders.

Markdown

Nearly all content on this site uses Markdown as the base format. We are using the Goldmark markdown parser, which is the default parser with Hugo. A complete guide to Markdown is beyond the scope of this guide. For markdown syntax, refer to the Hugo Markdown Guide or use other files on this site as examples. Everything after the frontmatter (after the second +++) is the markdown content for the page.

Use the Style Guide guide as a reference when writing content for this site.

Layout and Theme

Each page on this site is generated by Hugo’s templating engine using a layout. These layouts are found in the /layouts/ folder and the theme’s /layouts/ folder.

Hugo uses a system called “themes” to apply layouts and styles that can be shared between sites. This site - like rhino3d.com - uses the rhino3d.com-theme found in the /themes/ folder.

Hugo is very opinionated about looking up files; it has a complex lookup order system. In general, Hugo has a “specific-to-general” preference for looking up assets like layouts (and data). For example, the default layout applied to a page is first determined by whether or not there is a matching layout with the same name as the content’s parent folder. For example, this guide is in a subfolder of a folder called content/en/guides. Hugo will first look to see if the site’s /layouts folder contains a matching guides.html file and - if not - it will then search the themes/rhino3d.com-theme/layouts/ folder for a file called guides.html. If it doesn’t find those, it will apply a more general (or default) layout.

You can override which layout should be used by typing the layout’s title in the type = toml field at the top of the markdown file.

Types of content

There are 4 types of content on this site:

1. Index Pages
2. Guides
3. Samples
4. APIs

All types of content - with the exception of APIs - begin with toml, which the site uses to categories and sort the content into appropriate areas.

Index Pages

Index pages are interspersed throughout the site. The Welcome page, the Guides page, and the Samples page, are all examples of Index pages. The source for such pages start with an underscore _ and use the list.html template (rather than the single.html).

Here is an example of the toml frontmatter for a index page:

For illustrative purposes, the toml fields for these do the following:

• aliases: These are used to create redirects. Hugo can stub out a direct from the alias to this location.
• description: A brief description of the content, used for SEO, mouseovers, tooltips and social media unfurls.
• title: This is the title of the page. This is the html page title.
• type: A possible override to the page’s template.
• weight: The relative sort-order of this page in any collection of pages.

Guides

Guides are contained in the /content/en/guides/ directory. This very document you are reading is a Guide.

To create a new guide, simply create a new markdown file and place it in the /content/en/guides/ folder or subfolder. The file be in a folder with a descriptive name (using dashes -s as the word separator) and contain an index.md file with some toml frontmatter.

Here is an example of the YAML for this guide:

The toml fields for Guides determine:

• aliases: These are used to create redirects. Hugo can stub out a direct from the alias to this location.
• authors: The original - or responsible - author(s). These values are in the authors.yml file in themes/rhino3d.com-theme/data folder..
• categories: The category of the guide (General, Overview, Advanced).
• description: A brief description of the content, used for SEO, mouseovers, tooltips and social media unfurls.
• keywords: Keywords related to this guide (un-used, as of yet).
• languages: The programming languages this guide references.
• sdk: The Rhino SDK(s) that this guide pertains to.
• title: This is the title of the guide. This is the html page title.
• type: The layout html file used by Liquid (found in /layouts/) on the guide.
• weight: The relative sort-order of this page in any collection of pages.

etc.

Samples

Samples are contained in the /content/en/samples/ folder.

Here is an example of the YAML for this sample:

The toml fields here should look familiar to those found in the guides above.

APIs

The API documentation is automatically generated from source-code and cannot be edited “by hand.”

Other Frontmatter

Many of the pages, guides, and samples have additional frontmatter such as TODO and origin yaml field. These fields are used by the site to toggle different page features, such as the presence of a table-of-contents (toc = ) or whether or not a page is crawled by search-engines block_webcrawlers. In addition to those frontmatter entries shown above here are some of the more common additional frontmatter fields:

Admin

The [admin] namespace governs fields related to the editorial process used - internally - to draft, edit, and localize the page.

• TODO: (string) A note on what specifically needs to be done next. It shows up in the Site Admin page
• origin: (string) Used if the page is a conversion from a previous page. The origin field contains the URL address of the original source material. It is often used when setting up redirects from older content to the newer content.
• picky_sisters: (string) These are comments made by the Picky Sisters as editorial feedback to the author.
• state: (string) State identifies the part of the process that a document is in. It shows up in the Site Admin page page. The states we use are:
  • In Progress: This page is a work-in-progress, not yet ready for review, let alone translation.
  • To Edit: This page is ready for “Picky Sisters” review and editing, but not yet ready for translation.
  • Complete: This page is “substantially” complete and ready to be translated. It will show up in the translators’ localization status pages.

Page Options

The [page_options] namespace governs fields with optional page features such as:

• toc: (boolean) Determines whether or not to display the Table of Contents widget.
• byline: (boolean) Set to true to display a byline and the date this page was last edited.
• block_webcrawlers: (boolean) This controls whether or not the page is crawled by search-engine robots: it adds the appropriate html to the head to prevent search engine robots from crawling the page. This is frequently used for draft content. If not set, it defaults to false, allowing the page to be indexed.

Included In

The [included_in] namespace governs fields related to support on different platforms (“Windows”, “Mac”) and when the feature or subject was introduced:

• platforms: (list of strings) which operating systems this topic pertains to. If only one is included, a badge is rendered on the guide or sample that calls out this is a “Windows-only” feautre.
• since: (integer) The major version of Rhino this feature or topic was introduced in. If the current version of Rhino matches this number, a New badge might be rendered on the page.
• until: (integer) The major version of Rhino this feature or topic was deprecated (removed) in. If the current version of Rhino is greater than this number, we can render a deprecated warning or badge to call-out that this content is obsolete or removed.

_Build

This is a field to specify whether a page is listed as a page on the website - especially when iterating through pages in layouts/templates. The most common use of the list field is to set it to "never" like this:

Authors

To add a new author to the site, you must do three things:

1. Add an entry to the themes/rhino3d.com-theme/data/authors.yml file with the appropriate fields filled in.
2. Duplicate one of the index.md files in the content/en/authors folder and use the name: value that you added to the themes/rhino3d.com-theme/data/authors.yml file in step 1 above as the folder name.
3. Use the author’s name: value as a string in the authors = ['your_new_author_name'] toml entries in guides or samples.

That’s it.

Related topics

• Rhino Developer Docs Style Guide

Edit this page

Edit on GitHub

History

Admin