MACALCHEMIST OFFLINE SITEMAP MANAGER v0.1.5
================================================

Map your site without crawling your site.

A free, local-first sitemap maintenance and audit utility.

WHY THIS EXISTS
---------------
Most sitemap generators discover pages by crawling the live website. That is
convenient, but it also means generating crawler traffic against the server.
One reason Offline Sitemap Manager exists is very practical: a live-site
sitemap crawler once got the developer's IP blocked from his own website.

This program takes the opposite approach. It analyses a local copy, backup,
mirror or suitable export of the website instead.

WHAT IT DOES
------------
Offline Sitemap Manager maintains an approved sitemap baseline and helps you
review changes before generating replacement files. It can also surface useful
site-maintenance problems rather than merely collecting URLs.

It can flag or help review:

* ordinary new sitemap candidates
* canonical URLs which point somewhere else
* noindex pages
* approved URLs whose local files are missing
* unresolved internal links discovered from approved pages
* changed approved pages where lastmod may need attention
* historical/local pages which are not represented in the approved sitemap

The workflow is intentionally conservative: inspect first, approve deliberately,
then generate proposed output into a separate folder.

SAFE / USEFUL / FREE
--------------------
* No live-site crawling by the sitemap engine.
* No FTP, SSH, hosting-panel or API credentials.
* No automatic changes to the live website.
* No subscription.
* No scan quota.
* No artificial program URL cap. Standard sitemap-protocol limits still apply.
* Free software under GNU GPL v3.
* Coffee donations are entirely optional.

The Help menu contains optional browser/mail links for support and contact.
Those links open only when you deliberately choose them; the sitemap engine
itself remains local-only.

IMPORTANT LIMITATION
--------------------
You need a local copy, backup, mirror or suitable export of the website.

For traditional HTML/PHP/file-based sites this is often exactly what you already
keep as a backup or working copy. For database-driven CMSs, hosted site builders
or JavaScript applications, the filesystem alone may not represent every public
URL or its final metadata. Such platforms may require a separate helper/exporter.

Any future platform-specific helper should remain separate from the stable core
program. A helper can prepare a local snapshot or manifest for this program
without turning the sitemap manager itself into a collection of fragile CMS
integrations.

REQUIREMENTS
------------
Python 3.9+ is recommended. Tkinter is required for the GUI.

On Debian/Ubuntu-family Linux systems Tkinter may be provided separately as:

    sudo apt install python3-tk

No third-party Python packages are required.

STARTING THE PROGRAM
--------------------
Run:

    python3 offline_sitemap_manager_v015.py

The launcher offers:

    Open existing project...
    Create new site project...

The Help menu is available from both the launcher and the main program.

QUICK START — BUNDLED DEMO
--------------------------
1. Run offline_sitemap_manager_v015.py.

2. Click "Open existing project...".

3. Open:

       demo_project/sitemap-project.json

4. The project uses the bundled local dummy site:

       dummy_site/

   Its public URL is deliberately fictional:

       https://example.test/

5. Click "Initialise current snapshot" once.

6. Click "Audit existing path..." and enter:

       /

   The audit is deliberately designed to find:

   * articles/second.html        — ordinary CANDIDATE
   * orphan.html                 — ordinary unlinked CANDIDATE
   * private/noindex.html        — NOINDEX
   * legacy.html                 — CANONICAL_OTHER

7. Approve articles/second.html into "articles".
   Approve orphan.html into "main".

8. Leave the NOINDEX and CANONICAL_OTHER examples unapproved.

9. Generate the proposed files.

   Expected approved totals:

       main:      4
       articles:  3
       total:     7

PROJECT CREATION
----------------
The New Site Project form asks for:

* site name
* base URL, for example https://example.com/
* project folder
* local website root
* optional existing XML sitemap file(s)

If no sitemap is imported, the project starts with an empty approved baseline
and one sitemap group:

    main -> sitemap.xml

You can add further sitemap groups later.

NORMAL WORKFLOW
---------------
1. INITIALISE CURRENT SNAPSHOT

   Do this once when setting up a project. It records the current local site so
   routine scans focus on genuine changes rather than presenting every existing
   historical file as new.

2. SCAN FOR CHANGES

   Use this for routine maintenance after files have been added, changed or
   removed from the local website copy.

3. AUDIT EXISTING PATH...

   Use this deliberately when you know an older section contains sitemap gaps.
   For example:

       /
       /articles/
       /archive/2024/

4. REVIEW

   Nothing found by the scanner/auditor is automatically approved.

5. GENERATE PROPOSED FILES...

   Output is written to a separate timestamped directory. Review it before
   uploading anything to the website.

REVIEW STATUSES
---------------
CANDIDATE
    A locally resolvable page which can be considered for the sitemap.

NOINDEX
    The page declares noindex. Normally do not put it in the XML sitemap.

CANONICAL_OTHER
    The page declares a canonical URL different from itself. This is deliberately
    surfaced because it may be correct, or it may reveal a broken/stale canonical.

LINK_UNRESOLVED
    A discovered local-site link does not resolve to a page file.

APPROVED_CHANGED
    A previously approved local page has changed.

APPROVED_MISSING
    An approved URL no longer resolves locally. This is a warning only. Approved
    URLs are never automatically removed.

APPROVED BASELINE
-----------------
The Approved baseline tab is intentionally append-first.

You can:
* add an approved URL directly
* add sitemap groups
* export the approved URL list

Automatic removal is deliberately not provided.

EXCLUSIONS
----------
The Exclusions tab contains URL-path prefixes or globs which should never be
proposed as sitemap candidates.

Generic defaults exclude only common development trees such as:

    /.git/
    /.svn/
    /node_modules/

Add site-specific archives, admin areas or development folders yourself.

LASTMOD POLICIES
----------------
Approved URLs can use:

PRESERVE
    Keep the stored lastmod unchanged.

DAILY
    Use today's date when generated.

WEEKLY
    Update at most weekly.

FILE
    Derive lastmod from the mapped local page file.

DATAFILE
    Derive lastmod from matching local data files.

MANUAL
    Use a manually touched date.

OMIT
    Do not emit lastmod for that URL.

PROJECT SETTINGS
----------------
The Project settings tab lets you review or edit:

* site name
* local website root
* default sitemap group
* sitemap group labels
* sitemap output filenames
* optional custom ErrorDocument listing

Once an approved baseline exists, changing the base URL is deliberately
restricted. Create a new project for another site instead.

CUSTOM ERROR PAGES
------------------
Custom error pages are OFF by default.

If enabled in Project settings, the program reads local .htaccess ErrorDocument
directives and lists only targets which actually exist locally.

These links appear only in the human-readable sitemap. They never enter the XML
sitemap.

PHP, JAVASCRIPT AND DYNAMIC SITES
--------------------------------
Offline Sitemap Manager reads local source files; it does not run a web server,
PHP interpreter, JavaScript engine or database.

Consequences:

* PHP-generated descriptions may occasionally expose raw template expressions.
* JavaScript-created navigation may not be discoverable as ordinary links.
* Database-generated URLs cannot be inferred unless represented in the local
  snapshot/export or explicitly added.

This is deliberate. The program is a conservative local sitemap manager and
auditor, not a browser or live-site crawler.

GENERATED OUTPUT
----------------
Depending on the project configuration, generation produces:

* one XML sitemap per configured sitemap group
* sitemap_index.xml
* sitemap.htm — human-readable approved-site index
* sitemap-change-report.txt

All output is written to a new timestamped directory.

SELF TEST
---------
Run:

    python3 offline_sitemap_manager_v015.py --self-test

You can also skip the launcher:

    python3 offline_sitemap_manager_v015.py --project /path/to/sitemap-project.json

LICENCE
-------
Copyright © 2026 Stephen MacDonald-Brown.

Offline Sitemap Manager is free software licensed under the GNU General Public
License version 3 (GPLv3). The complete licence is supplied in LICENSE.txt.

GPLv3 permits commercial use as long as its terms are followed. Alternative
proprietary/commercial licensing for organisations that wish to redistribute or
integrate the software under different terms may be available from the copyright
holder.

CONTACT / BUG REPORTS
---------------------
sitemapper@macalchemist.net


WINDOWS PORTABLE BUILD
----------------------
The source release includes build_windows_v015.bat.

To build the portable Windows application:

1. Install Python 3 for Windows from python.org and make sure Python is added to PATH.
2. Open Command Prompt and install PyInstaller:

       py -m pip install pyinstaller

3. Double-click build_windows_v015.bat.

The finished portable application will be created at:

       dist\OfflineSitemapManager\OfflineSitemapManager.exe

The build script also copies README.txt, LICENSE.txt, CHANGELOG.txt and the
bundled demo project/site into the portable application folder when present.

The Windows build has been tested with Python 3.14 and PyInstaller 6.22.

NOTE ABOUT WINDOWS FILESYSTEMS
-----------------------------
Windows filesystems are normally case-insensitive, while many web servers are
case-sensitive. A site containing two distinct files such as Fred.html and
fred.html cannot be represented faithfully in an ordinary Windows snapshot.
This is a filesystem limitation rather than a sitemap-manager limitation.


SUPPORT
-------
If you find the program useful, you can buy me a coffee at:

    https://buymeacoffee.com/macalchemip

Coffee is appreciated, never required.

DEVELOPMENT DIRECTION
---------------------
The core sitemap engine is intentionally kept conservative and stable.

Potential future additions include:
* visual / graphical site-map HTML output
* separate platform-specific snapshot/manifest helpers

Intentionally not planned for the core program:
* live-site crawling
* FTP/SFTP/server uploads
* automatic deletion of approved sitemap URLs
