# SEO & AI Visibility

## SEO & AI Visibility

**Files:** `src/config/config.toml`, page frontmatter · **Skill level:** Beginner

Givo does the technical SEO for you: page titles and descriptions, canonical links, a sitemap, `robots.txt`, structured data for a non-profit organization, social preview cards, RSS, and files for AI assistants. Your job is to set your address and organization details, and to write good titles and descriptions.

### First, Set Your Address
```toml
[site]
  baseUrl = "https://www.your-domain.org"   # ships as "https://example.com"
```

Canonical links, the sitemap, `robots.txt`, RSS feeds, `llms.txt`, structured data, and social preview URLs all use it. Until you change it, `npm run build` prints a `[site]` warning. Don't deploy while you see it: every page would point search engines at `example.com`.

A `SITE_URL` environment variable on the build takes priority over `baseUrl`. On Vercel, the included `vercel.sh` sets one for you. `npm run generate-og-image` reads only `baseUrl`.

### Organization Details For Search
Search engines read your organization from `[organization]` in `config.toml`: the name, legal name, registration number, phone, email, address, office hours, founding year, and type. Set them once there (see [Organization Info](/givo/customization/organization-info/)); every page and the structured data use them.

```toml
[organization]
  type               = "NGO"            # NGO | Organization | LocalBusiness
  nonprofitStatus    = "Nonprofit501c3" # sample; empty leaves it out
  registrationNumber = "12-3456789"     # sample; `taxID` in structured data
  foundingYear       = "2009"           # sample
  sameAs             = []               # your charity register listing, Wikipedia, Wikidata
```

Givo ships with `type = "NGO"`, the schema.org type for a charity or non-profit. Use `LocalBusiness` only for a walk-in office or shop: it adds opening hours and a map pin (`[organization.geo]`). `nonprofitStatus` takes a schema.org value such as `Nonprofit501c3` (US) or `UKTrust` (UK); leave it empty if you are not sure. The sample values are marked `# sample`: replace them or clear them.

### Titles And Descriptions
Every page and entry accepts these frontmatter fields (`src/content/_file_format.md` lists them all):

```yaml
---
title: "Clean water wells"                          # shown on the page
metaTitle: "Clean water wells for six villages"     # search result title (optional)
description: "Six new wells so that families..."    # page summary
metaDescription: "Fund six wells, water tests, and local repair teams..."  # 140–160 characters (optional)
image: "/images/photos/cause-water-tap.jpg"         # social preview image (optional)
canonical: ""                                       # only if the page is a copy of another URL
robots: ""                                          # for example "noindex, follow"
keywords: ["clean water charity", "village wells"]
---
```

Titles get your tagline added: "Clean water wells for six villages - Your tagline". The tagline and the default description come from `seo.tagline` and `seo.siteDescription` in each `src/i18n/<language>.json`, and a value in `[site]` replaces them in every language:

```toml
[site]
  title            = "Givo"   # your organization name
  description      = ""       # empty: seo.siteDescription of each language
  tagline          = ""       # empty: seo.tagline of each language
  taglineSeparator = ""       # default is " - "
```

`disableTagline: true` turns the tagline off for one page. `[seo] author` is the default author (empty uses the organization name), and `[seo] keywords` is the default keywords list for pages without their own. `[seo] robots` ships with `max-snippet:-1, max-image-preview:large` so search and AI answers can quote your pages and show their images in full.

Replace the theme's sample tagline and description before launch: the files in `src/i18n/` ship with "Charity & Non-Profit Astro & Tailwind CSS Theme" and a description of the theme. See [Internationalization](/givo/customization/internationalization/#page-title-tagline-and-site-description).

### Structured Data (JSON-LD)
```toml
[seo.schema]
  enable  = true # false removes every JSON-LD block
  faqPage = true # FAQPage markup on /faq/
```

Givo builds it from your content, so it always matches what visitors see:

| Page | Structured data |
| --- | --- |
| Every page | Your organization (`NGO`, with address, phone, office hours, registration number, and a donate action pointing at `/donate/`), the website, and the page |
| Cause pages | A donate action for that cause (`/donate/?cause=<id>`) |
| Event pages | An `Event` with its dates, place (or online), and ticket price |
| Stories | `BlogPosting` with the author |
| `/faq/` | `FAQPage` with every question |
| Job pages | `JobPosting` with pay, type, and dates |
| Pages with a page header | Breadcrumbs |

<Aside type="note" title="No review stars in the markup">
  Givo never marks up reviews or ratings. Quotes hosted on your own site count
  as self-serving for Google, which doesn't show review stars for them. The
  supporter quotes still show on the page for visitors.
</Aside>

Keep the data true: job posting data is for real openings only, and the sample registration number, address, and events must be replaced before launch. After launch, test a page with Google's [Rich Results Test](https://search.google.com/test/rich-results).

### Social Preview Cards
```toml
[opengraph]
  image          = "/images/og-image.jpg" # fallback image, public/images/og-image.jpg
  generateImages = true    # a 1200×630 card for every page without its own image
  theme          = "light" # light | dark
  twitter        = ""      # your X (Twitter) handle
```

- A page with its own `image` (a cause, an event, a story) uses that photo.
- Every other page gets a card generated during `npm run build`, with your logo, the section, the page title, and the description, in your fonts and colors.
- `image` is the fallback card. Run `npm run generate-og-image` after you change the name, colors, or fonts (and after setting `baseUrl` and `[site]`) to redraw it.

### Sitemap, Robots, And Hidden Pages
- `/sitemap-index.xml` lists every page. Leave a page out with `excludeFromSitemap: true`, or every page in a folder with `[seo.sitemap] exclude` (it ships with `donate/thanks`). Draft pages are removed automatically.
- `/robots.txt` is built from `[seo.robotsTxt]`. Add paths crawlers must skip to `disallow`.

These pages ship hidden from search engines (`noindex`):

| Page | Why |
| --- | --- |
| `/home-appeal/`, `/home-community/` | Demo homepages. Remove `robots` and `excludeFromSitemap` from the one you make your home (see [Homepages](/givo/customization/homepages/)) |
| `/elements/` | The layout gallery, a reference for you |
| `/donate/thanks/` | The thank-you page after a gift |
| 404 pages | Not real pages |
| Story category and tag pages with fewer than 2 stories | Thin pages |

`/components/` (every Markdown shortcode) is indexed like a normal page. Delete it, or add `draft: true` to `src/content/pages/<language>/components.mdx`, if you don't want it on your site.

### AI Search And AI Assistants
People ask AI assistants which charities help children near them, or how a charity spends its money. Givo lets them read and cite your site, and gives you control over each kind of AI crawler.

**1. Choose which AI crawlers may visit**

```toml
[seo.robotsTxt]
  aiSearch       = true  # AI search and answer engines that fetch pages to cite them (ChatGPT search, Claude, Perplexity, ...)
  aiTraining     = true  # crawlers that collect content to train AI models (GPTBot, ClaudeBot, Google-Extended, CCBot, ...)
  contentSignals = false # true adds a Content-Signal line (contentsignals.org) with the two choices above
```

Each switch writes `robots.txt` rules for a list of crawlers in `src/lib/utils/aiCrawlers.ts`. `aiSearch = false` removes your site from those engines' answers; `aiTraining = false` opts out of training only. Neither affects Google Search or AI Overviews, which use the normal Googlebot and follow your regular search rules. `contentSignals` ships off because Lighthouse doesn't know the line yet and lowers the SEO score.

**2. `llms.txt` and Markdown copies**

```toml
[seo.ai]
  llmsTxt       = true # /llms.txt (index) and /llms-full.txt (all text), per language
  markdownPages = true # a Markdown copy of each cause, event, story, job, donate, FAQ, and impact page
```

- `/llms.txt` is a Markdown map of your site that some AI tools read; `/llms-full.txt` holds the text of every page. Both open with your organization facts from `[organization]` (name, registration number, phone, email, address, office hours, currency, the tax note, and the donate link), then your causes, giving, pages, events, stories, and jobs. Each language gets its own (`/fr/llms.txt`, `/ar/llms.txt`). See [AI Links & llms Files](/givo/features/ai-links-llms/).
- With `markdownPages`, a cause at `/causes/clean-water-wells/` is also served as `/causes/clean-water-wells.md`. The text pages, such as the policies, get one too. The included `public/_headers` (Netlify, Cloudflare Pages), `vercel.json`, and `public/.htaccess` (Apache) serve these as text and mark the `.md` copies `noindex`, so search engines don't index them in place of your pages.
- Leave a page out with `excludeFromAi: true`. Pages marked `noindex`, the thank-you page, and drafts are left out automatically.

Search engines don't document using `llms.txt`, so treat it as a convenience for AI tools, not as an SEO setting.

**3. The Ask AI links**

```toml
[settings.pageActions]
  enable    = true
  footer    = true  # a footer row with Ask AI links, the Markdown copy, and llms.txt on every page
  providers = ["chatgpt", "claude", "perplexity", "grok"] # empty hides the "Ask" links
```

Each Ask link opens the assistant with a question about the current page. The row shows in every footer layout.

### IndexNow (Bing And Others)
IndexNow tells Bing, Yandex, Seznam, and Naver which pages changed, so they update faster. Bing also feeds ChatGPT search and Copilot. It ships off.

1. Set a key of 8 to 128 letters, numbers, or dashes in `config.toml`: `indexNowKey = "your-key"` under `[seo.ai]`. The build publishes it at `/<key>.txt`.
2. Deploy.
3. After each deploy, run `npm run indexnow`. It sends the pages whose sitemap date changed in the last 7 days. `npm run indexnow -- --all` sends every page (first launch), `--days=30` a longer period, and `--dry-run` lists the pages without sending.

### Do It With AI
```text
Improve SEO for my charity. For every content file with a title in src/content/**/english/,
write a metaDescription of 140–160 characters from the page content, and a metaTitle under 60
characters where the title is vague. Don't change other fields. Then do the same in every other
language. Set seo.tagline and seo.siteDescription in each src/i18n/<language>.json and [seo]
keywords in src/config/config.toml for [ORGANIZATION, CAUSES, PLACES], and check that [site]
baseUrl is "[MY URL]".
```