> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.knapsack.cloud/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.knapsack.cloud/_mcp/server.

# Adding Documentation

## What you'll learn

We'll cover how to organize your content, create pages that make sense, and use Knapsack's tools to build documentation that grows with your design system.

*New to Knapsack? Start with [Navigating Knapsack](/get-started/editing-interface) to get familiar with the interface first.*

***

## Plan Your Content Structure

### The three ways to organize content in Knapsack

[**Pages**](/documentation/pages) are perfect for guidelines, processes, and explanations. Think of them like articles or guides.

[**Patterns**](/documentation/patterns) are for documenting components. They connect directly to your code and show live examples.

**Groups** help you organize everything. Use them to create logical sections and keep things tidy.

### Here's what works for most teams

Most teams find success with these main sections:

* **Get started** — Help people jump in quickly
* **Foundations** — Your design tokens, principles, and core guidelines
* **Components** — Individual UI elements with examples and code
* **Patterns** — Component combinations and layout templates that solve common design problems
* **Resources** — Contribution guides, tools, and helpful links

Don't overthink this part. You can always reorganize later as your needs change.

***

## Setting up your navigation

### Adding main sections

1. Click **Add New** in your sidebar or top nav
2. Choose what type of content you're creating: Page, Pattern, Group, or External Link
3. Give it a clear name and description
4. Click **Add**

That's it! Your new section appears in the navigation.

### Adding subsections

Want to add content under an existing section? Here's the quick way:

1. Hover over any main navigation item
2. Click the **plus (+) icon** that appears
3. Choose your content type and fill in the details
4. Click **Add**

### Keeping things organized

Need to move things around? No problem:

* **Drag** items using the **six-dot handle** **(⋮⋮)** to reorder them
* **Click the three dots (...)** next to any nav item to access Page Actions where you can rename, move, hide, or delete it
* **Group related content** together so it's easy to find

Learn more about [organizing your navigation](/documentation/navigation).

***

## Creating your first documentation page

### The basics

1. Navigate to where you want your page
2. Click **Add New** → **Page**
3. Add a descriptive title (this shows up in navigation)
4. Choose where it lives in your docs
5. Click **Add Page** and you're ready to start writing

### Adding tabs to organize your page

Pages can have multiple tabs to organize different types of content. After creating your page, click **Add Tab** to create additional sections.

**Common tab structures:**

* **Overview** and **Guidelines** — Separate basic info from detailed usage rules
* **Usage** and **Examples** — Split guidance from visual demonstrations
* **Do's and Don'ts** and **Accessibility** — Organize different types of guidelines
* **Getting Started** and **Advanced** — Structure content by user experience level

You can customize tab names to fit your content, so organize your information in whatever way makes most sense for your users.

### Building content with blocks

Knapsack uses [blocks](/documentation/blocks-overview) to help you create rich content. Think of them like building pieces you can mix and match.

Here's how to add them:

1. Enter edit mode on your page
2. Hover over any existing content
3. Click the **plus (+) button** that appears
4. Pick the block type you want

**Pro tip:** Hold Shift when selecting a block to add it above the current block instead of below.

### The blocks you'll use most

[**Text blocks**](/documentation/blocks-overview/managing-blocks/text-block) are your workhorses. Use them for paragraphs, lists, headings, and most of your writing.

[**Callout blocks**](/documentation/blocks-overview/managing-blocks/callout-block) are great for highlighting important info, tips, or warnings. They make key points stand out.

[**Image blocks**](/documentation/blocks-overview/embed-blocks/image-block) let you add screenshots, diagrams, or examples. Always add alt text for accessibility.

[**Shortcut blocks**](/documentation/blocks-overview/managing-blocks/shortcuts-block) create those handy tile layouts you see on overview pages. Perfect for linking to related content.

[**Divider blocks**](/documentation/blocks-overview/managing-blocks/divider-block) give you clean visual breaks between sections.

Want to see all available block types? Check out our complete [Content Blocks guide](/documentation/blocks-overview).

### Making your content scannable

**Use different block sizes:**

* Small (1/3 width) for side-by-side content
* Medium (1/2 width) for two-column layouts
* Large (2/3 width) for main content with sidebars
* Full width for most content

**Add breathing room with spacing:**

* None = standard spacing (fine for most cases)
* Small, Medium, or Large = extra space when you need clear breaks

**Enable block headers when they help:** Most blocks let you add titles and descriptions. Use them when they make your content clearer, skip them when they don't.

Learn more about [managing your blocks](/documentation/blocks-overview/managing-blocks).

***

## Documenting components with patterns

### Creating a pattern

Patterns are specifically designed for component documentation. Here's how to set one up:

1. Go to where you want it in your navigation
2. Click **Add New** → **Pattern**
3. Enter the component name (make it unique)
4. Choose where it lives in your docs
5. Connect to existing code if you have it
6. Click **Add Pattern**

Learn more about [working with patterns](/documentation/patterns).

### How patterns are organized

Patterns let you create different tabs to organize your content. Click **Add Tab** to see your options:

**Sub Page** — Create custom tabs like "Overview" or "Guidelines" for your written content, examples, and usage guidance

**Design Source** — Connect design files and specs (you can rename this tab to "Figma" or whatever fits your workflow)

**Template** — Connect to code that's already been linked to Knapsack by a developer (you can customize this tab name too)

You have full control over what tabs you create and what you call them, so organize your component documentation in whatever way makes sense for your team.

### Special blocks for patterns

[**Template Playground**](/documentation/blocks-overview/embed-blocks/template-playground) lets people interact with your component right in the docs. They can change props and see what happens. (Use this in Template tabs)

[**Template Variants**](/documentation/blocks-overview/embed-blocks/template-variants) automatically shows all the different versions of your component. It updates when your code changes, so no manual work. (Use this in Template tabs)

[**Template Specs**](/documentation/blocks-overview/embed-blocks/pattern-spec) display your component's API documentation wherever you need it. (Works in any tab type)

[**Design Source blocks**](/documentation/blocks-overview/managing-blocks/figma-component-block) embed live design files so design and code stay in sync. (Use this in Design Source tabs)

***

## Writing docs people actually use

### Start with what people need to know

Ask yourself: What questions do people have about this topic? What are they trying to accomplish? Start there.

### Make it easy to scan

* Use clear headings that describe what's in each section
* Break up long paragraphs with lists or examples
* Put the most important info first
* Use examples to show, not just tell

### Keep it practical

Give people specific steps and examples. Link to related resources. Anticipate their follow-up questions.

### Test with real people

The best way to know if your docs work? Watch someone try to use them. You'll quickly see where they get confused or stuck.

***

## Managing your content

### Moving and organizing blocks

Need to rearrange content? You've got options:

* **Drag blocks** using the **six-dot handle** **(⋮⋮)** for big changes
* **Use Move Up/Down** in the block menu for small adjustments
* **Move blocks between pages** if you put something in the wrong place

### Reusing content

* **Duplicate blocks** to save time on similar content
* **Copy successful layouts** to maintain consistency
* **Move content between pages** when you reorganize

### Keeping things current

* Review your docs regularly (quarterly works for most teams)
* **Knapsack automatically updates** component examples and design tokens when they're published, so your live demos stay current
* Update written explanations and screenshots when needed
* Ask your team what's confusing or missing

Learn more about [managing your blocks](/documentation/blocks-overview/managing-blocks).

***

## Quick start checklist

**Week 1: Get the structure right**

◯ Plan your main navigation sections

◯ Create groups for organizing content

◯ Add essential pages (getting started, key guidelines)

*Need help getting oriented in Knapsack? Check out [Navigating Knapsack](/get-started/editing-interface) to learn your way around the interface.*

**Week 2: Add your most important content**

◯ Document your most-used components

◯ Write getting started content

◯ Add examples and visuals

**Week 3: Polish and improve**

◯ Test navigation with team members

◯ Gather feedback on what's helpful

◯ Make adjustments based on what you learn

Remember: Good documentation is never "done." Start with the basics and keep improving based on how your team actually uses it.

***

## What's next?

Once you've got the hang of adding content, explore some of Knapsack's more advanced features:

* Connect your [Figma files](/figma-design-source) for automatic design updates
* Set up [code connections](/code-sources) for live component examples
* Use [design tokens](/design-tokens) to keep everything consistent
* Create templates for consistent documentation across components

The key is starting simple and building up over time. Your team will thank you for documentation that actually helps them get their work done.