Site Auditor Dashboard — User Guide

1. Introduction

1.1 What Is the Dashboard?

The Site Auditor Dashboard is a web-based tool that reads CSV files exported by Tom's Site Auditor (the Windows desktop application) and presents them as an interactive, filterable, sortable dashboard in your browser. It runs on your own web server — no external services, no cloud dependencies, no data leaves your hosting.

1.2 What Can It Do?

Load any scan's CSV exports and instantly see a summary of page health, issue breakdowns by severity and category, a prioritized action plan, and detailed tables you can filter, search, and sort. Upload multiple datasets and compare them side by side to track which issues are new, which are fixed, and which persist across scans. Generate a clean, printable client report you can hand to stakeholders.

1.3 How Does It Connect to Site Auditor?

After running a scan in the Site Auditor desktop app, you'll find two CSV files in the scan output folder: pages.csv and issues.csv. The dashboard reads these files. You can either upload them through the dashboard's built-in upload feature or copy them to the server via FTP/SFTP.

2. Requirements

2.1 Server Requirements

2.2 Browser Requirements

Any modern browser — Chrome, Firefox, Edge, Safari. The dashboard uses vanilla JavaScript with no external frameworks or dependencies. No browser plugins required.

2.3 Data Requirements

CSV files must be exported from Tom's Site Auditor. The dashboard validates column structure on upload and will reject files that don't match the expected format. At minimum, each dataset needs:

• pages.csv — must contain a URL column and a Status Code column
• issues.csv — must contain URL, Issue (or Type), and Severity columns

Optional columns like Score, Rating, Title, Word Count, Response Time, Fix, and Message are detected automatically and enable richer dashboard features when present.

3. Installation

3.1 Upload Files

Upload the dashboard files to your web server. The file structure should look like this:

3.2 Set Directory Permissions

The dashboard needs to create three directories during setup. Make sure the web server user (usually www-data or apache) can write to the dashboard root folder:

• config/ — stores settings.json with your account and configuration
• data/ — stores uploaded CSV datasets
• Both directories are auto-created on first setup

3.3 Navigate to the Dashboard

Open your browser and go to your dashboard URL (e.g. https://your-site.com/dashboard/). On the very first visit, you'll see the Setup Wizard.

3.4 Automatic Security

During setup, the dashboard automatically creates .htaccess protection files inside the config/, data/, and includes/ directories. These block direct HTTP access to sensitive files — your settings, CSV data, and PHP includes are never accessible via a browser URL. You don't need to create or manage these files yourself.

4. Setup Wizard

The setup wizard appears on first visit. It creates your admin account and configures basic security. You only see this screen once — after completing setup, it's replaced by the login page.

4.1 Account Creation

• Username — at least 3 characters. Letters, numbers, dots, dashes, underscores.
• Password — at least 8 characters. Stored as a bcrypt hash (never in plain text).

4.2 Enable CSV Upload

Check this box if you want to upload CSV files directly through the dashboard's web interface. If you prefer to manage files via FTP/SFTP only, leave it unchecked. You can change this later in Settings.

4.3 IP Restriction

Optionally restrict dashboard access to specific IP addresses. When enabled, only the listed IPs can reach the login page — all other visitors get a generic 403 error. Your current IP address is pre-filled for convenience.

4.4 Reverse Proxy Setting

If your server is behind Cloudflare, nginx, or another reverse proxy, check the "Behind a Reverse Proxy" box. This tells the dashboard to read the visitor's real IP from forwarded headers instead of the direct connection IP.

Leave this unchecked unless you know you're behind a proxy. When off, the dashboard uses only the direct TCP connection IP, which cannot be spoofed — this is the safer default.

4.5 Completing Setup

Click Complete Setup & Sign In. The dashboard creates the config/ and data/ directories, writes your settings, generates .htaccess protection files, and logs you in automatically.

5. Uploading Data

5.1 Exporting from Site Auditor

After running a scan in the Site Auditor desktop app, you'll find the output in the data/scans/ folder next to the executable. Each scan creates a timestamped subfolder (e.g. example.com-scan_2026-02-13_143022) containing:

• pages.csv — one row per crawled page with URL, status code, title, word count, response time, etc.
• issues.csv — one row per detected issue with URL, issue type, severity, message, and fix suggestion

5.2 Upload via Dashboard (Web Interface)

If CSV Upload is enabled in Settings, a collapsible "Manage Scan Data" panel appears at the top of the dashboard. Click the panel header to expand or collapse it. The panel provides two upload methods:

Method 1: Upload a Scan Folder (Recommended)

This is the fastest way to upload a complete scan. Select an entire Site Auditor scan folder from your PC — the folder name becomes the dataset name automatically, and the pages.csv and issues.csv files inside it are uploaded together.

1. Expand the Manage Scan Data panel.
2. In the Scan Folder field, click Choose Files (or Browse depending on your browser) and select the scan output folder from your PC. A preview will show the folder name and which CSV files were found.
3. Click Upload Scan. The dashboard creates the subfolder and uploads both CSV files automatically.

Method 2: Upload Individual Files

Below the folder picker, an "Or upload individual files" section lets you upload one CSV at a time to an existing dataset folder. This is useful for replacing a single file or uploading to the root data/ directory.

1. Select the Target Folder from the dropdown (choose an existing dataset or the root data/ directory).
2. Select the File Type — either pages.csv or issues.csv.
3. Choose the CSV file from your PC.
4. Click Upload. The dashboard validates the file (correct columns, file size, CSV structure) before accepting it.

5.3 Upload via FTP/SFTP

If you prefer not to use the web upload, you can copy files directly to the server:

1. Connect to your server via FTP/SFTP.
2. Navigate to dashboard/data/.
3. Create a subfolder with a date in the name (e.g. example.com-2026-02-13).
4. Upload pages.csv and issues.csv into that subfolder.
5. Refresh the dashboard — the new dataset appears in the dropdown.

5.4 Managing Datasets

Each subfolder in data/ is one dataset. The dashboard dropdown lists all valid subfolders sorted by the date found in the folder name (newest first). You can have up to 50 datasets by default (configurable).

The Manage Scan Data panel also shows a list of all existing datasets, including which CSV files each one contains and its last modified date. Each subfolder dataset has a Delete button to remove it directly from the dashboard — this deletes the CSV files and the subfolder. The root data/ directory cannot be deleted.

6. Dashboard Overview

6.1 Selecting a Dataset

Use the dropdown in the mode bar to select which dataset to view. Changing the selection reloads the page with the new dataset. The selected dataset name, date, page count, and issue count are shown in the header bar.

6.2 Summary Cards

The top row displays key metrics at a glance:

• Total Pages — number of pages in the dataset
• Total Issues — total number of issues detected across all pages
• Critical / Warning / Info — issue count broken down by severity
• Average Score — if your CSV includes a Score column, this shows the mean score across all pages

6.3 Severity Breakdown Chart

A horizontal bar chart shows the distribution of issues by severity. Each bar is color-coded: Critical in red, Warning in amber, Info in blue. The chart gives you an instant sense of whether the site has urgent problems or mostly minor issues.

6.4 Category Breakdown

Issues are also grouped by category — SEO, Content, Links, Performance, and Technical. Each category shows its issue count and a bar proportional to the total. This helps you see which area of the site needs the most attention.

6.5 Rating Distribution

If your CSV includes a Rating column, the dashboard shows how many pages fall into each rating band: Excellent, Good, Fair, and Poor. This is especially useful for communicating overall site health to non-technical stakeholders.

7. Pages Table

7.1 Overview

The Pages section shows every crawled page as a row in a sortable, filterable table. Columns include URL, Status Code, and any optional columns present in your CSV (Title, Word Count, Response Time, Score, Rating, Issue Count, and others). The section header shows the current visible count and includes Export Filtered, Export All, and Print Section buttons for exporting data.

7.2 Sorting

Click any column header to sort by that column. Click again to reverse the sort direction. The active sort column and direction are indicated by an arrow in the header.

7.3 Filter Toolbar

The pages table has a full filter toolbar with multiple filter types that can be combined:

• Status filters — filter by HTTP status code (200, 301, 404, etc.). Each button shows the count.
• Rating filters — filter by page rating (Excellent, Good, Fair, Poor) when your CSV includes a Rating column.
• Issue filters — filter to pages that Have Issues or are Clean (zero issues).
• Presets — quick-access buttons: Pages with Issues, Low Scores, and Clean Pages.
• URL Search — type in the search box to filter rows by URL. Matching is applied as you type.
• Clear All — resets all active filters at once.

The visible row count updates in the header as you apply filters.

7.4 Column Toggles

Below the filter toolbar, a column toggle bar lets you show or hide individual columns. Click a column name to toggle its visibility. Show All and Clear All buttons are provided for convenience. Some columns are hidden by default to keep the table readable (e.g. Final URL, Anchor Summary, Link Suggestions, Tip, H1) — toggle them on when you need them.

7.5 Pagination

For large datasets, the table is paginated. Use the controls at the bottom to navigate pages, and the page size dropdown to show 50, 100, 250, or 500 rows per page (default is 100). Sorting and filtering work across the full dataset — pagination only controls which slice you're viewing.

7.6 Page–Issue Linking

Click any page row to filter the Issues table to show only issues for that URL. A blue indicator banner appears above the Issues table showing "Showing issues for: [URL]" with a Clear button to remove the filter. Click the same row again to deselect it.

7.7 Export & Print

The header bar provides three export options:

• Export Filtered — downloads a CSV containing only the currently visible (filtered) rows
• Export All — downloads a CSV of all rows, ignoring any active filters
• Print Section — opens a print-friendly view of the table

8. Issues Table

8.1 Overview

The Issues section lists every detected issue as a row. Columns include URL, Issue Type, Severity, and (if present in your CSV) the diagnostic message and fix recommendation. The section header shows the current visible count and includes Export Filtered, Export All, and Print Section buttons.

8.2 Filter Toolbar

The issues table has a comprehensive filter toolbar with three groups that can be combined:

• Severity filters — click Critical, Warning, or Info to show only issues of that severity. Each button shows the count. Click again to toggle off. Multiple severity filters can be active simultaneously.
• Type filters — individual buttons for each issue type found in your data (e.g. MissingMetaDescription, BrokenLink, TitleTooLong). Each shows its count. These let you drill into a specific issue type.
• Presets — quick-access buttons: Warnings & Critical, SEO Issues, Content Issues, and Link Issues. Category presets only appear when matching issue types exist in your data.
• Clear All — resets all active filters at once.

8.3 Column Toggles

Below the filter toolbar, a column toggle bar lets you show or hide individual columns. Some columns are hidden by default (e.g. Extra, Tip) to keep the table readable. Use Show All and Clear All for quick toggling.

8.4 Page Link Indicator

When you click a page row in the Pages table (see Section 7.6), the Issues table automatically filters to that URL. A blue indicator banner appears above the table showing "Showing issues for: [URL]" with a Clear button. This combines with the other filters — you can view, for example, only Critical issues for a specific page.

8.5 Jump to Page

Click any issue row to scroll the Pages table to the corresponding page and highlight it. This works across pagination — if the target page is on a different pagination page, the dashboard switches to the correct page first, then scrolls and highlights the row.

8.6 Bulk Selection & Clipboard

Use the checkboxes on the left to select individual issues or the header checkbox to select all visible rows. A selection bar appears showing the count, a Copy URLs button that copies all selected issue URLs to your clipboard, and a Deselect all button. This is useful for sharing a list of pages that need fixing.

8.7 Export & Print

The same export options as the Pages table: Export Filtered (visible rows only), Export All (ignoring filters), and Print Section.

9. Priority Action Plan

9.1 What Is It?

The Priority Action Plan is a ranked list of issues sorted by impact. Instead of showing raw data, it answers the question: "What should I fix first?" Each entry shows the issue type, how many pages it affects, its severity, and a recommended fix action.

9.2 How Priorities Are Calculated

The prioritizer scores each issue type using the formula: priority score = severity weight × affected page count. The severity weights are: Critical = 3, Warning = 2, Info = 1. Issues affecting more pages with higher severity are ranked first. Each entry also shows an effort estimate (Low, Medium, or High) with an explanation of what the fix involves.

The result is a practical, prioritized todo list — fix the top items first for maximum improvement.

9.3 Template Fix Detection

When 60% or more of affected pages for an issue share the same URL path prefix (e.g. all in /blog/), the issue is flagged with a TEMPLATE FIX /path/ badge. This means you likely only need to fix one template file to resolve the issue across all affected pages — a single change with outsized impact.

9.4 Fix Suggestions

Each priority item includes a plain-English fix recommendation drawn from the Site Auditor's issue data. These are actionable steps like "Rewrite page title to 30-60 characters" or "Add a meta description of 120-160 characters" — designed to be handed directly to a developer or content editor.

10. Comparison Mode

10.1 What Is Comparison Mode?

Comparison mode lets you select two datasets and see what changed between them. This is designed for tracking progress — scan a site, make fixes, scan again, and compare the two to verify your fixes actually worked.

10.2 How to Compare

The comparison controls are in the mode bar at the top of the dashboard, next to the dataset selector. You need at least two datasets for comparison to be available.

1. In the mode bar, find the Compare section with two dropdown selectors.
2. Select scan A from the first dropdown (typically the older scan).
3. Select scan B from the second dropdown (typically the newer scan).
4. Click the Compare button. The dashboard loads both datasets and computes the diff. Use the Clear link to exit comparison mode and return to the normal view.

10.3 Comparison Results

The comparison view shows three categories:

10.4 Summary Statistics

The comparison header shows total counts for each category, along with an overall delta (e.g. "+12 new, -8 fixed"). A net negative number means you're making progress.

11. Client Report

11.1 What Is the Client Report?

The Client Report generates a clean, print-ready HTML page summarizing the scan results. It's designed to be shared with clients, stakeholders, or team members who don't need access to the full dashboard.

11.2 Generating a Report

Click the 📄 Generate Client Report link below the mode bar. A new browser tab opens with the report. From there, use your browser's Print function (Ctrl+P / ⌘P) to save it as a PDF or send it to a printer.

11.3 What's Included

The client report contains:

• Site summary — total pages, total issues, severity breakdown
• Category breakdown — issue counts by SEO, Content, Links, Performance, Technical
• Top priorities — the priority action plan with page counts and fix recommendations
• Bar charts — visual severity and category distributions
• Version stamp — dashboard version and generation date for reference

11.4 Self-Contained Output

The report is a single HTML page with all styles inline — no external dependencies, no JavaScript required. It renders identically in any browser and prints cleanly on A4 or Letter paper.

12. Settings

Access settings by clicking the Settings link in the header bar (visible when logged in).

12.1 Change Password

Enter a new password and confirm it. Minimum 8 characters. Leave both fields blank to keep your current password. Your username cannot be changed after setup.

12.2 Enable CSV Upload

Toggle the upload feature on or off. When disabled, the Manage Scan Data panel is hidden from the dashboard and upload API requests are rejected.

12.3 IP Restriction

Enable or disable IP whitelisting. When enabled, enter one IP address per line. Only these IPs can access the dashboard — all others receive a 403 Forbidden response before reaching the login page.

Your current IP is displayed at the top of the settings page for reference. Always make sure your own IP is in the list before saving.

12.4 Reverse Proxy

The "Behind a Reverse Proxy" checkbox appears within the IP restriction section. When checked, the dashboard reads visitor IPs from headers set by Cloudflare (CF-Connecting-IP), nginx (X-Real-IP), or other proxies (X-Forwarded-For).

When unchecked (the default), only the direct TCP connection IP (REMOTE_ADDR) is used. This is safer because forwarded headers can be spoofed by anyone unless your server is actually behind a trusted proxy.

12.5 Info Panel

The settings page displays an information panel at the top showing your current username, detected IP address, session lifetime (default: 8 hours), and maximum number of datasets allowed (default: 50).

13. Status Page

Access the status page by clicking the Status link in the header bar, or by adding ?status to your dashboard URL (e.g. https://your-site.com/dashboard/?status). This page runs a self-check of your installation and reports the health of each component.

13.1 What's Checked

Each check shows a green pass or red fail indicator. If anything fails, the description tells you exactly what to fix. A summary at the top shows the total number of passed and failed checks.

14. Troubleshooting

14.1 Setup Wizard Won't Complete

Usually a permissions issue. The dashboard needs to create the config/ directory and write settings.json. Check that the web server user has write access to the dashboard root folder. On most hosting this means 755 permissions with the correct owner.

14.2 Locked Out by IP Whitelist

If your IP changed and you can't access the dashboard:

1. Connect to your server via FTP/SFTP or SSH.
2. Open config/settings.json in a text editor.
3. Find "ip_whitelist_enabled" and change it to false, or update the "ip_whitelist" array with your new IP.
4. Save the file and refresh the dashboard.

14.3 Upload Fails with "File Too Large"

The dashboard has a 20 MB default limit, but PHP itself may have lower limits. Check your hosting's PHP configuration for upload_max_filesize and post_max_size. Both need to be at least as large as your CSV file. Many shared hosts default to 2 MB — contact your host to increase this.

14.4 CSV Rejected as Invalid

The dashboard validates CSV structure on upload. Common causes:

• Wrong file — make sure you're uploading pages.csv and issues.csv from a Site Auditor scan, not a different tool's export
• Modified columns — if you edited the CSV and changed column headers, validation will fail
• Encoding — files must be UTF-8. Site Auditor exports UTF-8 by default

14.5 Dashboard Shows No Data After Upload

Make sure the dataset subfolder name contains a date in YYYY-MM-DD format. Folders without a recognizable date are ignored by the dataset scanner. For example, my-scan won't work but my-scan-2026-02-13 will.

14.6 Comparison Shows Everything as "New"

This usually means the two datasets have very different page sets. The comparison matches issues by URL + issue type — if the older scan crawled different pages (different scope, different max pages setting), most issues won't have a matching pair and will show as new. For reliable comparisons, scan the same URL with the same settings both times.

14.7 .htaccess Files Not Working

The auto-generated .htaccess files require Apache with mod_rewrite enabled and AllowOverride set to All (or at least FileInfo) in your Apache configuration. If you're on nginx, the .htaccess files have no effect — you'll need to add equivalent deny rules to your nginx configuration directly.

14.8 Session Expires Too Quickly

The default session lifetime is 8 hours. This is set during setup and stored in settings.json as session_lifetime (in seconds, default 28800). You can edit this value directly in the JSON file if needed. Note that PHP's own session.gc_maxlifetime must also be at least this long.