docs: apply user feedback improvements

docs/content/0.getting-started/0.introduction.md

@@ -19,7 +19,29 @@ and easy to miss best practices.
 
 Nuxt Sitemap automatically generates the sitemap for you based on your site's content, including lastmod, image discovery and more.
 
-Ready to get started? Check out the [installation guide](/docs/sitemap/getting-started/installation) or learn more on the [Controlling Web Crawlers](https://nuxtseo.com/learn/controlling-crawlers) guide.
+## Installation
+
+You have two installation options:
+
+**Option 1: Install the full SEO suite** (Recommended)
+
+The easiest way to get started is by installing `@nuxtjs/seo`, which includes Nuxt Sitemap along with other essential SEO modules:
+
+```bash
+npx nuxi@latest module add seo
+```
+
+**Option 2: Install Nuxt Sitemap standalone**
+
+If you only need sitemap functionality, you can install just the sitemap module:
+
+```bash
+npx nuxi@latest module add sitemap
+```
+
+Both options will work perfectly fine. The `@nuxtjs/seo` module is a collection of modules including sitemap, robots, og-image, and more.
+
+Ready to configure? Check out the [installation guide](/docs/sitemap/getting-started/installation) or learn more on the [Controlling Web Crawlers](https://nuxtseo.com/learn/controlling-crawlers) guide.
 
 ## Features
 

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

@@ -25,10 +25,33 @@ You can debug this further in Nuxt DevTools under the Sitemap tab.
 
 ## Configuration
 
-At a minimum the module requires a Site URL to be set, this is to only your canonical domain is being used for
+At a minimum the module requires a Site URL to be set, this is to ensure only your canonical domain is being used for
 the sitemap. A site name can also be provided to customize the sitemap [stylesheet](/docs/sitemap/guides/customising-ui).
 
-:SiteConfigQuickSetup
+### Site Config Quick Setup
+
+The easiest way to configure your site URL is using the [Nuxt Site Config](/docs/site-config/getting-started/introduction) module, which is automatically installed with `@nuxtjs/sitemap`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  site: {
+    url: 'https://example.com',
+    name: 'My Awesome Site'
+  }
+})
+```
+
+Alternatively, you can configure the site URL directly in the sitemap module options:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  sitemap: {
+    siteUrl: 'https://example.com'
+  }
+})
+```
+
+Note: Using the `site` config is recommended as it provides site-wide configuration that can be used by other SEO modules.
 
 To ensure search engines find your sitemap, you will need to add it to your robots.txt. It's recommended to use the [Nuxt Robots](/docs/robots/getting-started/installation) module for this.
 

docs/content/2.guides/0.data-sources.md

@@ -55,13 +55,79 @@ You have several options for providing user sources:
 
 For sitemap data that only needs to be updated at build time, the `urls` function is the simplest solution. This function runs once during sitemap generation.
 
+The `urls` function should return an array of URL objects. Each URL object can be:
+- A string (just the path)
+- An object with sitemap properties
+
+**URL Object Structure:**
+
+```ts
+interface SitemapUrl {
+  loc: string              // Required: The URL path
+  lastmod?: string | Date  // Optional: Last modification date
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+  priority?: number        // Optional: 0.0 to 1.0
+  images?: ImageEntry[]    // Optional: Associated images
+  videos?: VideoEntry[]    // Optional: Associated videos
+  _sitemap?: string        // Optional: Which sitemap this URL belongs to (for multi-sitemaps)
+}
+```
+
+**Examples:**
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  sitemap: {
+    urls: async () => {
+      // Example 1: Return simple string paths
+      return [
+        '/about',
+        '/contact',
+        '/products/special-offer'
+      ]
+    }
+  }
+})
+```
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  sitemap: {
+    urls: async () => {
+      // Example 2: Return detailed URL objects
+      return [
+        {
+          loc: '/about',
+          lastmod: new Date(),
+          changefreq: 'monthly',
+          priority: 0.8
+        },
+        {
+          loc: '/blog/my-post',
+          lastmod: '2024-01-15',
+          changefreq: 'weekly',
+          priority: 0.9
+        }
+      ]
+    }
+  }
+})
+```
+
 ```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
+      // Example 3: Fetch from an API
+      const response = await fetch('https://api.example.com/posts')
+      const posts = await response.json()
+
+      return posts.map(post => ({
+        loc: `/blog/${post.slug}`,
+        lastmod: post.updated_at,
+        changefreq: 'weekly',
+        priority: 0.7
+      }))
     }
   }
 })

docs/content/2.guides/2.dynamic-urls.md

@@ -11,6 +11,61 @@ The module supports two types of data sources:
 - JSON responses from API endpoints
 - XML sitemaps from external sources
 
+## URL Structure Reference
+
+All sitemap URLs must follow a specific structure. Whether you're creating a JSON endpoint or using the `urls` function, your URLs should match this format:
+
+```ts
+interface SitemapUrl {
+  loc: string              // Required: The URL path (e.g., '/blog/my-post')
+  lastmod?: string | Date  // Optional: Last modified date (ISO 8601 format or Date object)
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+  priority?: number        // Optional: 0.0 to 1.0 (default: 0.5)
+  images?: ImageEntry[]    // Optional: Array of image objects
+  videos?: VideoEntry[]    // Optional: Array of video objects
+  _sitemap?: string        // Optional: Specify which sitemap this URL belongs to (for multi-sitemap setups)
+  alternatives?: Array<{   // Optional: For i18n/alternate language URLs
+    hreflang: string       // Language code (e.g., 'en', 'fr', 'es')
+    href: string           // Full URL to alternative version
+  }>
+}
+```
+
+**Example JSON Response:**
+
+```json
+[
+  {
+    "loc": "/blog/getting-started",
+    "lastmod": "2024-01-15T10:30:00Z",
+    "changefreq": "weekly",
+    "priority": 0.8
+  },
+  {
+    "loc": "/products/widget",
+    "lastmod": "2024-01-20",
+    "changefreq": "daily",
+    "priority": 0.9,
+    "images": [
+      {
+        "loc": "https://example.com/images/widget.jpg",
+        "title": "Widget Product Image"
+      }
+    ]
+  }
+]
+```
+
+**Minimal Example:**
+
+```json
+[
+  "/blog/post-1",
+  "/blog/post-2",
+  "/about"
+]
+```
+
 ## Using External XML Sitemaps
 
 If you have an existing XML sitemap, you can reference it directly in your configuration:
@@ -189,3 +244,111 @@ export default defineNuxtConfig({
 ```
 
 ::
+
+## Verifying Your Dynamic URLs
+
+After setting up dynamic URLs, it's important to verify they're working correctly. Here's how to check:
+
+### 1. Test Your API Endpoint Directly
+
+First, verify your API endpoint returns the correct data structure:
+
+```bash
+# Visit your endpoint in the browser or use curl
+curl http://localhost:3000/api/__sitemap__/urls
+```
+
+**Expected Response:**
+
+```json
+[
+  {
+    "loc": "/blog/my-post",
+    "lastmod": "2024-01-15T10:30:00Z",
+    "changefreq": "weekly",
+    "priority": 0.8
+  }
+]
+```
+
+If this doesn't work, check:
+- The endpoint file exists at `server/api/__sitemap__/urls.ts`
+- The endpoint returns an array of URL objects or strings
+- There are no TypeScript or runtime errors
+
+### 2. Check Your Sitemap XML
+
+Once your endpoint is working, visit your sitemap to see if URLs appear:
+
+```bash
+# Single sitemap
+http://localhost:3000/sitemap.xml
+
+# Multiple sitemaps
+http://localhost:3000/posts-sitemap.xml
+http://localhost:3000/pages-sitemap.xml
+```
+
+**What to Look For:**
+
+```xml
+<url>
+  <loc>https://example.com/blog/my-post</loc>
+  <lastmod>2024-01-15T10:30:00Z</lastmod>
+  <changefreq>weekly</changefreq>
+  <priority>0.8</priority>
+</url>
+```
+
+### 3. Use Nuxt DevTools
+
+Open Nuxt DevTools (in development mode) and navigate to the Sitemap tab to:
+- See all URLs in your sitemap
+- View which sources contributed which URLs
+- Debug data source issues
+- Inspect URL properties
+
+### 4. Common Issues
+
+**URLs not appearing in sitemap:**
+
+- Verify the `sources` array in `nuxt.config.ts` includes your endpoint
+- Check that your endpoint URL path is correct (should start with `/`)
+- Ensure the endpoint returns data in the correct format
+- For multi-sitemap setups, verify the `_sitemap` property matches your sitemap name
+
+**URLs appear in development but not production:**
+
+- If using build-time `urls` function, ensure it's async and awaits data
+- For runtime `sources`, verify the endpoint is accessible in production
+- Check that your data source is available at build/runtime
+
+**Wrong domain in sitemap URLs:**
+
+- The `loc` field should be a path only (e.g., `/blog/post`), not a full URL
+- Set your site URL in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  site: {
+    url: 'https://example.com'
+  }
+})
+```
+
+### 5. Testing in Production
+
+Before deploying, test your sitemap generation:
+
+```bash
+# Build your site
+npm run build
+
+# Preview the production build
+npm run preview
+
+# Visit your sitemap
+http://localhost:3000/sitemap.xml
+```
+
+This ensures your dynamic URLs work correctly in the production environment.