Configuration

Linx Books uses file-system hierarchy and frontmatter metadata within Markdown files to dynamically generate navigation, layouts, and page structures.

Frontmatter Metadata

Every documentation page supports metadata configuration at the beginning of the file, enclosed by a --- block (written in YAML syntax).

---
title: Configuration Guide
description: Learn how to configure your documentation layout.
tag: Advanced
order: 1
---

Supported Properties

The system parses the following frontmatter properties exactly:

Table of Contents & Anchors

The Table of Contents (ToC) displayed on the right side of the desktop layout is automatically extracted from the headings in your markdown:

• Level Extraction: The system parses H1 (#), H2 (##), and H3 (###) markdown headers.
• Anchor Generation: It automatically generates URL anchors using slugified versions of the heading text.
• Scroll Syncing: As you scroll through the page, the active section highlight in the ToC updates dynamically to match your current viewport position.

Thumbnails & Icons Configuration

You can customize the thumbnail representation for pages, groups, and folders by adding a thumbnail configuration block to the frontmatter.

thumbnail:
  type: icon | local | remote
  value: string

Thumbnail Types

1. Whitelisted Icon (type: icon): Uses a curated set of high-quality Lucide icons mapped by key.

   • value: One of the whitelisted keys:

     • book
     • folder
     • file
     • settings
     • terminal
     • layers
     • shield (alias: security)
     • quick (renders Zap icon)
     • info (renders HelpCircle icon)
     • compass
     • cpu
     • play
     • layout
     • code
     • split (alias: route)
     • lab (renders FlaskConical icon)
     • database (alias: data)
     • ai (renders Astroid icon)

   Example:

   yamlCopy

   thumbnail:
     type: icon
     value: settings

2. Local Image (type: local): Renders a local image asset located inside your webapp's public directory.

   • value: The absolute path relative to the /public root.

   Example:

   yamlCopy

   thumbnail:
     type: local
     value: /images/workorder-flow.png

3. Remote Image (type: remote): Renders any external image asset via URL.

   • value: The full HTTP/HTTPS URL of the image.

   Example:

   yamlCopy

   thumbnail:
     type: remote
     value: https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?auto=format&fit=crop&w=120&q=80

Default Fallbacks

If a page does not specify any thumbnail, or if a local/remote image fails to load, the system will automatically fall back to standard icons depending on the context:

• Documentation page: Curated FileText icon
• Collapsible folder: Curated Folder / FolderOpen icon
• Document group (Catalog): Curated BookOpen icon

Banners Configuration

You can customize the cover banner for documentation pages and group landing pages by adding a banner configuration block to the frontmatter.

banner:
  type: local | remote
  value: string

Banner Types

1. Local Image (type: local): Renders a local image asset located inside your webapp's public directory.

   • value: The absolute path relative to the /public root.

   Example:

   yamlCopy

   banner:
     type: local
     value: /banners/project-banner.png

2. Remote Image (type: remote): Renders any external image asset via URL.

   • value: The full HTTP/HTTPS URL of the image.

   Example:

   yamlCopy

   banner:
     type: remote
     value: https://example.com/banner.png

Design Recommendations & Behavior

• Recommended Ratio: Aspect ratios of 16:9 (e.g. 1280x720) or 21:9 (e.g. 1600x900) are recommended.
• Responsive Styling: Banners are responsive, matching a 16:9 ratio on mobile/tablet viewports and expanding to a wide 21:9 ratio on larger screens.
• Skeleton Loading: Includes a built-in skeleton loading card animation that prevents layout shifts while images are loading.
• Error Fallback: If no banner is provided, or if the image fails to load, the page automatically falls back to the standard compact header layout with zero visual regressions.