doc: sync from nuxt-seo

docs/0.getting-started/1.installation.md

@@ -0,0 +1,59 @@
+---
+title: 'Install Nuxt Sitemap'
+description: 'Get started with Nuxt Sitemap by installing the dependency to your project.'
+navigation:
+  title: 'Installation'
+---
+
+1. Install `@nuxtjs/sitemap` dependency to your project:
+
+```bash
+npx nuxi@latest module add sitemap
+```
+
+2. Set Site Config
+
+It's recommended to always set a canonical site URL to avoid duplicate content issues.
+
+You can set your site URL in [many ways](/site-config/guides/setting-site-config), the easiest is `nuxt.config` or `.env`:
+
+While optional, it's also recommended to set a `name` as this will be displayed on your sitemap.
+
+::code-group
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  site: {
+    url: 'https://example.com',
+    name: 'My Awesome Website'
+  },
+})
+```
+
+```bash [.env]
+NUXT_PUBLIC_SITE_URL=https://example.com
+```
+::
+
+Sitemap URLs will have their [trailing slashes](/nuxt-seo/guides/trailing-slashes) removed by default. If you want to keep them, you can set the `trailingSlash` option to `true`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  site: {
+    // optional: only if you have trailing slashes enabled
+    trailingSlash: true
+  },
+})
+```
+
+3. Preview your Sitemap
+
+After you've set up the module, if you visit `/sitemap.xml` you can see the generated sitemap.
+
+This has been generated with [Application Sources](/sitemap/getting-started/data-sources).
+
+4. Next Steps
+
+- You may want to add your own sources, see [Dynamic URLs](/sitemap/guides/dynamic-urls).
+- Have 1000's of pages? Consider using [Multiple Sitemaps](/sitemap/guides/multi-sitemaps).
+- Ready to go Live? See [Submitting Your Sitemap](/sitemap/guides/submitting-sitemap).

docs/0.getting-started/2.data-sources.md

@@ -0,0 +1,117 @@
+---
+title: Data Sources
+description: Learn how the Nuxt Sitemap sources work.
+---
+
+Every URL within your sitemap will belong to a source.
+
+A source will either be a User source or a Application source.
+
+## Application Sources
+
+Application sources are sources generated automatically from your app. These are in place to make using the module more
+convenient but may get in the way.
+
+- `nuxt:pages` - Statically analysed pages of your application
+- `nuxt:prerender` - URLs that were prerendered
+- `nuxt:route-rules` - URLs from your route rules
+- `@nuxtjs/i18n:pages` - When using the `pages` config with Nuxt I18n. See [Nuxt I18n](/sitemap/integrations/i18n) for more details.
+- `@nuxt/content:document-driven` - When using Document Driven mode. See [Nuxt Content](/sitemap/integrations/content) for more details.
+
+### Disabling application sources
+
+You can opt out of application sources individually or all of them by using the `excludeAppSources` config.
+
+::code-group
+
+```ts [Disable all app sources]
+export default defineNuxtConfig({
+  sitemap: {
+    // exclude all app sources
+    excludeAppSources: true,
+  }
+})
+```
+
+```ts [Disable pages app source]
+export default defineNuxtConfig({
+  sitemap: {
+    // exclude static pages
+    excludeAppSources: ['nuxt:pages'],
+  }
+})
+```
+
+::
+
+## User Sources
+
+When working with a site that has dynamic routes that isn't using [prerendering discovery](/sitemap/guides/prerendering), you will need to provide your own sources.
+
+For this, you have a few options:
+
+## 1. Build time: provide a `urls` function
+
+If you only need your sitemap data concurrent when you build, then providing a `urls` function is the simplest way to provide your own sources.
+
+This function will only be run when the sitemap is generated.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  sitemap: {
+    urls: async () => {
+      // fetch your URLs from a database or other source
+      const urls = await fetch('https://example.com/api/urls')
+      return urls
+    }
+  }
+})
+```
+
+### 2. Runtime: provide a `sources` array
+
+If you need your sitemap data to always be up-to-date at runtime, you will need to provide your own sources explicitly.
+
+A source is a URL that will be fetched and is expected to return an array of Sitemap URL entries.
+
+::code-group
+
+```ts [Single Sitemap]
+export default defineNuxtConfig({
+  sitemap: {
+    sources: [
+      // create our own API endpoints
+      '/api/__sitemap__/urls',
+      // use a static remote file
+      'https://cdn.example.com/my-urls.json',
+      // hit a remote API with credentials
+      ['https://api.example.com/pages/urls', { headers: { Authorization: 'Bearer <token>' } }]
+    ]
+  }
+})
+```
+
+```ts [Multiple Sitemaps]
+export default defineNuxtConfig({
+  sitemap: {
+    sitemaps: {
+      foo: {
+        sources: [
+          '/api/__sitemap__/urls/foo',
+        ]
+      },
+      bar: {
+        sources: [
+          '/api/__sitemap__/urls/bar',
+        ]
+      }
+    }
+  }
+})
+```
+
+::
+
+You can provide any number of sources, however, you should consider your own caching strategy.
+
+You can learn more about data sources on the [Dynamic URLs](/sitemap/guides/dynamic-urls) guide.

docs/0.getting-started/3.stackblitz.md

@@ -0,0 +1,15 @@
+---
+title: "Reproductions: Stackblitz"
+description: Create minimal reproductions for Nuxt Sitemap or just experiment with the module.
+---
+
+You can use the Nuxt Sitemap Stackblitz playgrounds for either:
+- Playing around with the module in a sandbox environment
+- Making reproductions for issues (Learn more about [Why Reproductions are Required](https://antfu.me/posts/why-reproductions-are-required))
+
+## Stackblitz Playgrounds
+
+- [Dynamic URLs](https://stackblitz.com/edit/nuxt-starter-dyraxc?file=server%2Fapi%2F_sitemap-urls.ts)
+- [i18n](https://stackblitz.com/edit/nuxt-starter-jwuie4?file=app.vue)
+- [Manual Chunking](https://stackblitz.com/edit/nuxt-starter-umyso3?file=nuxt.config.ts)
+- [Nuxt Content Document Driven](https://stackblitz.com/edit/nuxt-starter-a5qk3s?file=nuxt.config.ts)

docs/0.getting-started/4.faq.md

@@ -0,0 +1,24 @@
+---
+title: FAQ
+description: Frequently asked questions about Nuxt Sitemap.
+---
+
+## Why is my browser not rendering the XML properly?
+
+When disabling the [XSL](/sitemap/guides/customising-ui#disabling-the-xls) (XML Stylesheet) in, the XML will
+be rendered by the browser.
+
+If you have a i18n integration, then it's likely you'll see your sitemap look raw text instead of XML.
+
+![Broken XML because of xhtml namespace.](/sitemap/formatting-error.png)
+
+This is a [browser bug](https://bugs.chromium.org/p/chromium/issues/detail?id=580033) in parsing the `xhtml` namespace which is required to add localised URLs to your sitemap.
+There is no workaround besides re-enabled the XSL.
+
+## Google Search Console shows Error when submitting my Sitemap?
+
+Seeing "Error" when submitting a new sitemap is common. This is because Google previously
+crawled your site for a sitemap and found nothing.
+
+If your sitemap is [validating](https://www.xml-sitemaps.com/validate-xml-sitemap.html) correctly, then you're all set.
+It's best to way a few days and check back. In nearly all cases, the error will resolve itself.

docs/0.getting-started/_dir.yml

@@ -0,0 +1 @@
+title: Getting Started

docs/1.integrations/0.i18n.md

@@ -0,0 +1,98 @@
+---
+title: Nuxt I18n
+description: How to use the Nuxt Sitemap module with Nuxt I18n.
+---
+
+Out of the box, the sitemap module will integrate directly with [@nuxtjs/i18n](https://i18n.nuxtjs.org/).
+You will need to use v8+ of the i18n module.
+
+I18n configuration can get quite complicated, so it's important to figure out what mode you're using.
+
+## Modes
+
+### Automatic I18n Multi Sitemap
+
+When certain conditions are met then the sitemap module will automatically generate a sitemap for each locale:
+- If you're not using `no_prefix` strategy
+- Or if you're using [Different Domains](https://i18n.nuxtjs.org/docs/v7/different-domains),
+- And you haven't configured the `sitemaps` option
+
+This looks like:
+```shell
+> ./sitemap_index.xml
+> ./en-sitemap.xml
+> ./fr-sitemap.xml
+# ...etc
+```
+
+These sitemaps will include [app sources](/sitemap/getting-started/data-sources). The `nuxt:pages` source
+will automatically determine the correct `alternatives` for your pages.
+
+If you need to opt-out of app sources, use `excludeAppSources: true`.
+
+### I18n Pages
+
+If you have enabled `i18n.pages` in your i18n configuration, then the sitemap module will automatically generate a single sitemap
+using the configuration.
+
+This sitemap will not include [app sources](/sitemap/getting-started/data-sources).
+
+You can add additional URLs using `sources`.
+
+## Dynamic URLs with i18n
+
+To simplify the sitemap output, any dynamic URLs you provided will not have i18n data and will exist
+only within the default locale sitemap.
+
+To help you with this, the module provides two options: `_i18nTransform` and `_sitemap`.
+
+### `_i18nTransform`
+
+If you want the module to convert a single URL into all of its i18n variants, you can provide the `_i18nTransform: true` option.
+
+```ts [server/api/__sitemap__/urls.ts]
+export default defineSitemapEventHandler(() => {
+  return [
+    {
+      loc: '/about-us',
+      // will be transformed into /en/about-us and /fr/about-us
+      _i18nTransform: true,
+    }
+  ]
+})
+```
+
+### `_sitemap`
+
+Alternatively, you can specify which locale sitemap you want to include the URL in using `_sitemap`.
+
+```ts [server/api/__sitemap__/urls.ts]
+export default defineSitemapEventHandler(() => {
+  return [
+    {
+      loc: '/about-us',
+      _sitemap: 'en',
+    }
+  ]
+})
+```
+
+## Debugging Hreflang
+
+By default, the XML stylesheet doesn't show you the hreflang tags. You will need to view the page source to see them.
+
+Don't worry, these are still visible to search engines.
+
+If you'd like to visually see the hreflang tag counts, you can [Customise the UI](/sitemap/guides/customising-ui).
+
+```ts
+export default defineNuxtConfig({
+  sitemap: {
+    xslColumns: [
+      { label: 'URL', width: '50%' },
+      { label: 'Last Modified', select: 'sitemap:lastmod', width: '25%' },
+      { label: 'Hreflangs', select: 'count(xhtml)', width: '25%' },
+    ],
+  }
+})
+```