Toroidal Entry Settings

Toroidal Entry Settings (toroidal)

In the position settings for platen.display.menu, you can add entries to the site menu. These settings define an entry using the Toroidal feature to add a webring’s navigation to the site menu without having to redefine each part of the navigation manually.

If you’re hosting the webring, you can use the page_path setting to add navigation for a member using the site’s styling. To add navigation for a webring hosted on another site, or if you want more control over how the webring’s navigation is rendered, use the partial_path setting.

In both cases, you must define the feature setting for the entry as toroidal and may define the weight setting to control the ordering of the webring in the site menu.

Navigation entries using page_path or partial_path with the default partial you can copy from your webring’s administration page follow the same format:

  • They’re added inside a grouping entry and have the navigation items nested inside it, matching the definition for the webring member’s navigation page as normal, except they follow the styling for the Platen site menu.
  • You can use the display_name setting to override the name of the containing item in the site menu for the webring’s navigation. If you don’t specify a display name, the webring’s name is used instead.
  • You can use the collapse or flatten settings to override how the webring’s navigation is displayed in the site menu.
  • You can use the class setting to add extra CSS classes to the webring navigation in the site menu.
  • If you’re using the partial_path setting, you can add arbitrary settings to this entry that your partial is aware of. The entire entry is passed to the partial when it’s rendered along with the context for the page the menu is being rendered on.
Metadata

ID

https://platen.io/modules/platen/config/site/display/menu/toroidal/schema.json

Type

object

JSON Schema

Definition
{
  "$id": "https://platen.io/modules/platen/config/site/display/menu/toroidal/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Defines an entry for a Toroidal webring in the site menu.\n\nhttps://platen.io/modules/platen/config/site/display/menu/toroidal/",
  "properties": {
    "collapse": {
      "description": "Specifies whether to collapse the webring entry in the site menu.\n\nhttps://platen.io/modules/platen/config/site/display/menu/toroidal/#collapse",
      "title": "Collapse Webring Entry",
      "type": "boolean"
    },
    "display_name": {
      "description": "Specifies a display name for the containing element in the site menu.\n\nhttps://platen.io/modules/platen/config/site/display/menu/toroidal/#display_name",
      "title": "Display Name",
      "type": "string"
    },
    "feature": {
      "description": "Specifies the name of the Platen feature this entry should use to write HTML in the menu.\n\nhttps://platen.io/modules/platen/config/site/display/menu/toroidal/#feature",
      "enum": "toroidal",
      "title": "Feature Name"
    },
    "flatten": {
      "description": "Specifies whether to flatten the webring entry in the site menu.\n\nhttps://platen.io/modules/platen/config/site/display/menu/toroidal/#flatten",
      "title": "Flatten Webring Entry",
      "type": "boolean"
    },
    "page_path": {
      "description": "Specifies the path from the site's base URL for the member page to add navigation for.\n\nhttps://platen.io/modules/platen/config/site/display/menu/toroidal/#page_path",
      "title": "Page Path",
      "type": "string"
    },
    "partial_path": {
      "description": "Specifies the path to a partial to render for the webring navigation in the menu.\n\nhttps://platen.io/modules/platen/config/site/display/menu/toroidal/#partial_path",
      "title": "Partial Path",
      "type": "string"
    }
  },
  "title": "Toroidal Entry Settings",
  "type": "object"
}

Feature Name (feature)

Specifies the name of the Platen feature this entry should use to write HTML in the menu. To add a Toroidal webring nav, this value must be toroidal.

Metadata

Enums

toroidal

Page Path (page_path)

Specifies the path from the site’s base URL for the member page to add navigation for.

For example, if you’re hosting a webring in the content/neat-sites folder and your site’s member page in the webring is at content/neat-sites/very-cool.md, you would specify this value as neat-sites/very-cool.

If it specifies an invalid value, such as a page that doesn’t exist or isn’t a Toroidal webring member page, Hugo raises an error.

If neither this setting nor partial_path are defined, Hugo raises an error.

Metadata

Type

string

Partial Path (partial_path)

Specifies the path to a partial to render for the webring navigation in the menu.

You can get a partial for this purpose by following these steps:

  1. Navigate to the administration page for the webring on the host’s site.
  2. Find the section for your member page.
  3. Use the “Copy Platen menu partial” button to copy the partial HTML to your clipboard.
  4. Create a new file in the partials folder for your site, like partials/webring.html.
  5. Paste the partial HTML into the new file.
  6. Save the file.

For example, if you copied the Platen menu partial for your site from the webring’s administration page to partials/super-neat-webring/nav.html, you would specify super-neat-webring/nav for this value.

If you specify a value that Hugo can’t resolve to a partial, Hugo raises an error.

If neither this setting nor page_path are defined, Hugo raises an error.

Metadata

Type

string

Display Name (display_name)

Specifies a display name for the containing element in the site menu. If this value isn’t specified, the webring’s name is used instead.

Metadata

Type

string

Collapse Webring Entry (collapse)

Specifies whether to collapse the webring entry in the site menu. Collapsed entries are displayed with a clickable arrow that expands and collapses the webring’s entries, defaulting to collapsed.

This setting is incompatible with flatten. A webring entry can be collapsed or flattened, but not both.

Metadata

Type

boolean

Flatten Webring Entry (flatten)

Specifies whether to flatten the webring entry in the site menu. Flattened entries are displayed with the grouping entry bolded above a the webring’s entries without additional spacing or indenting for those entries.

This setting is incompatible with collapse. A webring entry can be collapsed or flattened, but not both.

Metadata

Type

boolean
Edit this page