Documentation Template Guide

This guide explains how to structure new documentation pages for consistency and better organization.

Frontmatter Template

Use this template when creating new .md files in the docs folder:

---
title: Your Page Title
description: Brief description (used for SEO and preview)
parent: ParentPageTitle  # Optional: for nested pages (must match another page's title)
category: CategoryName   # Required: e.g., SpringAI, General, Guides
order: 2                 # Required: controls sorting within category (1, 2, 3...)
tags: [tag1, tag2, tag3] # Optional: relevant keywords for searchability
layout: layouts/doc.liquid
---

# Your Page Title

Your content starts here...

Field Explanations

Field	Required	Purpose
`title`	Yes	Page title (appears in sidebar and navigation)
`description`	Yes	Brief description (displayed on page and in metadata)
`category`	Yes	Grouping category (SpringAI, Guides, General, etc.)
`order`	Yes	Sort order within category (lower numbers appear first)
`parent`	No	Parent page title for nested pages
`tags`	No	Array of keywords for better discoverability
`layout`	Yes	Always use `layouts/doc.liquid`

Directory Structure

docs/
├── index.md                    # Homepage
├── SpringAI/
│   ├── index.md               # Category overview
│   ├── gettingStarted.md      # Getting started guide
│   ├── examples/
│   │   └── essentials.md      # Example page
│   └── guides/
│       ├── setup.md
│       └── deployment.md
├── Guides/
│   ├── index.md
│   └── advanced-topics.md
└── TEMPLATE.md                # This file

Collections

The .eleventy.js config provides these collections:

docs - All pages sorted by order
docsByCategory - Pages grouped by category, each sorted by order

Use these for custom navigation or organization.

Adding New Pages

Create a new .md file in the appropriate directory
Add the frontmatter template above
Ensure order is unique within the category
Fill in title, description, and tags
Build the site to verify appearance

Best Practices

Descriptions: Keep to 1-2 sentences, descriptive enough for SEO
Tags: Use lowercase, hyphen-separated keywords
Order: Use increments of 10 (10, 20, 30...) for flexibility when adding pages
Parent: Only for 2-level nesting; try to keep structure flat when possible
Categories: Use existing categories when possible for consistency

Features

Page metadata with description appears below the title
Tags displayed as badges below metadata
Dark mode support built-in
Table of contents auto-generated from headings
Responsive design for all screen sizes