Manuals and Catalogs Layout
The manuals layout provides a powerful card-based system for organizing and displaying related content in catalogs. This layout is the single, generic catalog engine used for all card catalogs (manuals, reports, examples, benchmarks, applications, machines, use cases, nested catalogs). Parent pages act as catalogs; child pages appear as cards.
1. Key Features
- Card-Based Navigation
-
Automatically generates visual cards for related pages based on tags and parent-catalog relationships.
- Font Awesome Integration
-
Supports both image illustrations and Font Awesome icons for page cards using the
page-illustrationattribute. - Flexible Tagging System
-
Uses
page-tagsandpage-cards-tagattributes to control which pages appear in catalogs.page-cards-tagaccepts one or more tags. - Hierarchical Organization
-
Implements parent-catalog relationships for nested content organization. A catalog can list page types or other catalogs.
- Multi-Tag Support
-
Can group cards by different tags with optional group titles when multiple tags are listed in
page-cards-tag.
2. Unified Usage
Use the manuals layout for every catalog and control what appears with :page-cards-tag:.
// Parent (catalog) page
:page-layout: manuals
:page-cards-tag: example, benchmark, report // one or more types
:page-cards-within-module: true // limit search to this module
// Child (card) pages
:page-tags: example // or benchmark/report/…
:description: Short summary shown on the card
:page-illustration: fa-solid fa-flask // or image path3. Page Attributes for Manuals Layout
Essential attributes for catalog pages:
= Catalog Title
:page-layout: manuals
:page-tags: catalog-name,catalog
:page-cards-tag: catalog,manual
:page-cards-within-module: false
:page-cards-title: Display Title for Cards
:page-illustration: fa-solid fa-database
:parent-catalogs: parent-catalog-nameEssential attributes for manual pages:
= Manual Title
:page-tags: manual,specific-topic
:parent-catalogs: catalog-name
:description: Brief description for card display
:page-illustration: fa-solid fa-gear4. Attribute Reference
- page-layout
-
Set to
manualsto use the catalog layout - page-tags
-
Tags for the current page, typically includes
catalogfor catalog pages ormanualfor content pages - page-cards-tag
-
Specifies which tags to look for when building the card list
- page-cards-within-module
-
true(default) searches within current module,falsesearches across all modules - page-cards-across-components
-
Optional; when present and not
false, searches across components (use when you want a site‑wide catalog) - page-cards-title
-
Optional title displayed above the cards
- page-illustration
-
Font Awesome class (e.g.,
fa-solid fa-database) or image path - parent-catalogs
-
Specifies which catalog this page belongs to
- description
-
Brief description shown on the page card
5. Category‑Aware Styling
Cards are tinted and badged by type. On catalog pages that appear as cards (i.e., a catalog-of-X listed inside another catalog), you can add a secondary category tag to recolor the Catalog card automatically while keeping the badge label as "Catalog".
Accepted type tags (singular or plural): example, benchmark, report, manual, application, machine, usecase, catalog.
:page-layout: manuals
:page-tags: catalog, benchmarks // Catalog-of-benchmarks (tinted green)
:page-cards-tag: benchmarkThe badge color and card tint follow the tag; the label remains "Catalog" to indicate the page is a catalog.
6. Font Awesome Icons
The system automatically detects Font Awesome classes by looking for the fa- prefix:
- Font Awesome Icon
-
page-illustration: fa-solid fa-databaserenders as<i class="fa-solid fa-database"></i> - Image File
-
page-illustration: ROOT:diagram.pngrenders as an<img>element
7. Examples
See the catalog example for a working demonstration of the manuals layout system.