Show URLs Dry Run Command

The --show-urls command allows you to preview all URLs that will be generated by Marmite without actually building the site. This serves as a dry run to understand your site structure and verify URL patterns before generation.

What is --show-urls?

The --show-urls command is a non-destructive way to:

• Preview your site's URL structure
• Verify slug generation for all content
• Check how your content will be organized
• Plan your site navigation
• Debug URL-related issues
• Create external sitemaps or documentation

Basic Usage

Run the command pointing to your input folder:

$ marmite myblog --show-urls

This will display a comprehensive list of all URLs organized by content type.

Output Format

The command outputs a comprehensive JSON structure containing all URLs organized by content type:

{
  "posts": [
    "/getting-started.html",
    "/why-to-use-marmite.html",
    "/tutorial-python-tutorial-part-1.html"
  ],
  "pages": [
    "/about.html",
    "/contributors.html",
    "/pages.html"
  ],
  "tags": [
    "/tag-tutorial.html",
    "/tag-docs.html",
    "/tags.html"
  ],
  "authors": [
    "/author-rochacbruno.html",
    "/author-marmite.html",
    "/authors.html"
  ],
  "series": [
    "/series-python-tutorial.html",
    "/series.html"
  ],
  "streams": [
    "/index.html",
    "/tutorial.html",
    "/streams.html"
  ],
  "archives": [
    "/archive-2025.html",
    "/archive-2024.html",
    "/archive.html"
  ],
  "feeds": [
    "/index.rss",
    "/tutorial.rss",
    "/index.json",
    "/tutorial.json"
  ],
  "pagination": [
    "/index-1.html",
    "/index-2.html",
    "/tag-docs-1.html"
  ],
  "file_mappings": [
    "/favicon.ico",
    "/robots.txt"
  ],
  "misc": [
    "/index.html"
  ],
  "summary": {
    "posts": 33,
    "pages": 5,
    "tags": 43,
    "authors": 5,
    "series": 2,
    "streams": 3,
    "archives": 4,
    "feeds": 106,
    "pagination": 64,
    "file_mappings": 2,
    "misc": 1,
    "total": 268,
    "meta": {
      "url": "",
      "absolute_urls": false
    }
  }
}

With Base URL

When you have a base URL configured in your marmite.yaml or use the --url flag:

$ marmite myblog --show-urls --url "https://myblog.com"

The output will show absolute URLs and the metadata will reflect this:

{
  "posts": [
    "https://myblog.com/getting-started.html",
    "https://myblog.com/why-to-use-marmite.html"
  ],
  "summary": {
    "meta": {
      "url": "https://myblog.com",
      "absolute_urls": true
    }
  }
}

Understanding the Output

JSON Structure

The output is organized into categories with each containing an array of URLs:

1. posts: Individual blog posts with dates
2. pages: Static pages without dates
3. tags: Tag archive pages and the tags index page
4. authors: Author pages and the authors index page
5. series: Series pages and the series index page
6. streams: Content streams and the streams index page
7. archives: Yearly archive pages and the archives index page
8. feeds: All RSS and JSON feed URLs
9. pagination: Pagination pages (e.g., /index-2.html, /tag-docs-1.html)
10. file_mappings: Mapped files (e.g., /favicon.ico, /robots.txt)
11. misc: Other generated files

Summary Section

The summary object provides:

• Counts: Number of items in each category
• total: Total number of URLs generated
• meta: Contains the base URL and whether absolute URLs are used

"summary": {
  "posts": 33,
  "total": 268,
  "meta": {
    "url": "https://myblog.com",
    "absolute_urls": true
  }
}

Use Cases

1. Pre-deployment Verification

Before deploying your site, use --show-urls to verify all content will be accessible:

$ marmite myblog --show-urls | grep "404"
$ marmite myblog --show-urls | wc -l  # Count total URLs

2. Processing URLs with JSON

Extract specific URL types using JSON tools like jq:

# Get all post URLs
$ marmite myblog --show-urls | jq -r '.posts[]'

# Get total count
$ marmite myblog --show-urls | jq '.summary.total'

# Get feed URLs only  
$ marmite myblog --show-urls | jq -r '.feeds[]'

# Export to other formats
$ marmite myblog --show-urls > site-urls.json

3. Debugging Slug Generation

Check how your content titles are converted to URL slugs:

$ marmite myblog --show-urls | jq -r '.posts[]' | grep "my-complex-title"

4. Planning Site Navigation

Use the output to plan your site's navigation structure by seeing all available pages and their URLs.

5. CI/CD Integration

Include --show-urls in your CI pipeline to verify expected URLs are generated:

- name: Verify site structure
  run: |
    marmite content --show-urls > urls.json
    # Check if specific URLs exist
    jq -e '.posts[] | select(. == "/getting-started.html")' urls.json
    # Verify minimum URL count  
    [ $(jq '.summary.total' urls.json) -ge 50 ] || exit 1

Combining with Other Options

The --show-urls command respects configuration overrides:

# Check URLs with different pagination
$ marmite myblog --show-urls --pagination 5

# Check URLs with a specific theme
$ marmite myblog --show-urls --theme mytheme

# Check URLs with search enabled
$ marmite myblog --show-urls --enable-search true

Notes

• The command only reads your content files; it doesn't write anything to disk
• Draft posts are excluded from the output (except in the draft stream)
• The command uses the same URL generation logic as the actual site builder
• URLs are generated using the url_for Tera function internally
• File mappings are included in the file_mappings array
• The output is formatted as JSON for easy parsing and integration
• Use tools like jq to extract specific data from the JSON output

Comparison with Site Generation

Unlike marmite myblog output/ which generates the complete site:

• --show-urls only reads and analyzes content
• No HTML files are generated
• No templates are rendered
• No static files are copied
• No file system writes occur

This makes it perfect for quick checks and automation without the overhead of full site generation.

The --show-urls command is an essential tool for understanding and verifying your site structure before committing to a full build.

Please consider giving a ☆ on Marmite Github repository, that helps a lot!