# Pages & Content

Every page on your site is a markdown file in the `pages/` directory.

## File organization

```
pages/
  home.md              → yourdomain.com/
  features.md          → yourdomain.com/features
  pricing.md           → yourdomain.com/pricing
  docs/
    docs-home.md       → yourdomain.com/docs
    getting-started.md → yourdomain.com/docs/getting-started
    themes.md          → yourdomain.com/docs/themes
```

Subdirectories become URL path segments. The `slug` frontmatter field can override the default URL.

### Slug-based auto-rename

When you change a page's `slug` in frontmatter, the build automatically renames the file to match. If `pages/docs/old-name.md` has `slug: /docs/new-name`, the next build moves it to `pages/docs/new-name.md`.

This keeps filenames and URLs in sync without manual renaming. The old group sidebar entry is cleaned up automatically — no stale links.

## Frontmatter

Every page starts with YAML frontmatter between `---` fences:

```yaml
---
title: Page Title
description: A short description for meta tags and search results.
slug: /custom-url
layout: default
---
```

### Required fields

| Field | What it does |
|---|---|
| **title** | Page title. Appears in page heading, browser tab, and meta tags. |
| **description** | Meta description for SEO and social sharing. |

### Optional fields

| Field | What it does |
|---|---|
| **slug** | Custom URL path. Overrides the file-path-based default. |
| **sidebarGroupShown** | Name of the group whose sidebar to display on this page. |
| **groupMember** | List of groups this page belongs to. See [Groups](#groups). |
| **tabTitle** | Override the browser tab title independently of the page heading. See [SEO — Browser Tab Title](/docs/seo#browser-tab-title). |
| **tabTitleSuffix** | Override the suffix appended to the tab title. Set to `"none"` to suppress. |
| **draft** | Set to `true` to hide this page from production builds. Visible in dev server with a DRAFT banner. See [Content Generation](/docs/content-generation#draft-mode). |

## Groups

Groups are named collections of pages defined in `settings/groups.md`. A group can be displayed as a header dropdown, a footer column, or a page sidebar.

```yaml
# settings/groups.md
groups:
  - name: docs
    links:
      - Getting Started: /docs/getting-started
      - Themes: /docs/themes
```

### Page membership

Add `groupMember` to a page's frontmatter to include it in a group's sidebar:

```yaml
---
title: My Page
sidebarGroupShown: docs
groupMember:
  - docs
  - guides: Custom Label
---
```

- **`sidebarGroupShown`** — which group's sidebar appears on this page
- **`groupMember`** — which groups this page belongs to (with optional custom labels)

Ordering is controlled by the link list position in `groups.md` — no numbers needed.

## Link targets

Append `+newtab` to any link URL to force it to open in a new window. Append `+sametab` to keep an external link in the same window. The default behavior is: external links open in a new window, internal links open in the same window.

This works in settings files (header, footer, groups) and in markdown content:

```markdown
[Same Tab](/docs/pages-and-content#link-targets+sametab)
[New Tab](/docs/pages-and-content#link-targets+newtab)
```

## Anchor links

Every heading automatically gets a URL-friendly ID. `## Getting Started` becomes `id="getting-started"`. Link to it from anywhere:

```markdown
[Jump to section](#getting-started)
[See themes docs](/docs/themes#custom-colors)
```

Cross-page anchors (`/page#id`) work with instant navigation — the page loads and scrolls to the target.

### Inline anchors

Place an anchor anywhere with `{#id}` on its own line:

```markdown
{#pricing-table}
| Plan | Price |
| ---- | ----- |
| Free | $0/mo |
```

Now `[See pricing](#pricing-table)` scrolls to the table. IDs must be lowercase letters, numbers, and hyphens.

## Buttons in content

Add a button on its own line with `button:`:

```markdown
button: Get Started: /docs/getting-started
button: View Demo: /demo +outline
```

See [Buttons & Links](/docs/buttons-and-links) for variants, custom colors, and the full modifier reference.

## Markdown features

sitemd supports standard markdown plus common extensions:

- **Headings** — `# H1` through `###### H6` (auto-generate anchor IDs). Multiple `#` headings are handled automatically for SEO. See [Headings](/docs/headings).
- **Bold and italic** — `**bold**`, `*italic*`
- **Links** — `[text](url)` — supports `+newtab` / `+sametab` suffixes
- **Images** — `![alt](url)` with resizing, cropping, filters, and layouts. See [Images](/docs/images).
- **Code blocks** — Fenced with triple backticks, with language highlighting
- **Blockquotes** — `> quoted text`
- **Tables** — Standard pipe-delimited tables
- **Lists** — Ordered and unordered, with nesting
- **Horizontal rules** — `---`
- **Buttons** — `button: Label: /slug` on its own line
- **Embeds** — `embed: URL` on its own line. See [Embeds](/docs/embeds).
- **Cards** — `card: Title` on its own line. See [Cards](/docs/cards).
- **Inline anchors** — `{#id}` on its own line
- **Inline HTML** — Write raw HTML directly in your markdown. See [Inline HTML](/docs/inline-html).
- **Alignment** — `center:` / `/center` and `right:` / `/right` fences. See [Content Alignment](/docs/content-alignment).

## Layouts

Pages with `sidebarGroupShown` set get a two-column layout with a sidebar. All other pages get a single-column layout.

## Settings files

Your site's configuration lives in `settings/` as markdown files:

- **`settings/meta.md`** — Site title, brand name, description, URL
- **`settings/header.md`** — Header navigation, brand display, theme toggle. See [Navigation](/docs/navigation).
- **`settings/footer.md`** — Footer content, copyright, social links
- **`settings/groups.md`** — Named page groups for sidebars, header dropdowns, and footer columns
- **`settings/build.md`** — Build options (port, directories, sitemap toggle)
- **`settings/theme.md`** — Colors, fonts, layout dimensions per theme mode

Each file uses frontmatter for the actual values and markdown body for documentation. Edit a value, save, and your site rebuilds automatically.