Skip to main content
YORE
Yore

Docs Layout

Published:

Yore provides a docs layout specifically engineered for deep documentation, featuring a 3-column structure to optimize navigation and readability.

Activation

The docs layout can be applied to content using the following methods:

  • Directory-based (Automatic)

    Place your Markdown files within the content/docs/ directory. Hugo will automatically assign the docs type to these pages.

  • Configuration

    To apply the layout to specific paths or sections without moving files, utilize the cascade option in hugo.yaml:

    cascade:
  - type: docs
    target:
      path: '{/shortcodes,/shortcodes/**}'

    cascade can also be configured in the front matter in shortcodes/_index.md.

Options

  • Section (_index.md)
    • docsNavCollapsed: bool, whether the section navigation is collapsed.
  • Page (index.md)
    • docsIcon: string, the icon for the specific entry.
    • docsIconClass: string, CSS classes applied to the docsIcon wrapper.

Design Concept

While the Series feature can organize articles of varying spans, technical documentation demands a more structured environment for cross-referencing. The Docs layout is the common 3-column layout seen in Docusaurus, Vitepress, and MkDocs—a long-proven and efficient layout. A large part of Yore's series is built upon the solid foundation of Docusaurus.

Unlike my previous work Deca which utilizes swup for AJAX transitions, Yore uses standard page loads. This avoids the maintenance overhead of re-initializing every JavaScript and ensures that user-defined scripts or third-party libraries function natively without additional configuration.

Yore also avoids direct section linking within the navigation to minimize maintenance complexity. From a technical writing and reading perspective, standalone section pages often introduce more friction than utility.

#layout #documentation #configuration