Publishing your project

Publishing a NaturaList project is a four-step process managed entirely through the Manage screen inside the app. Your spreadsheet never leaves your machine. Instead, a compilation step produces a checklist.json file that the live app serves to all users.

The compilation pipeline

Your spreadsheet
        ↓  (upload via Manage screen or URL)
   Linked files (media, maps, ...)
        ↓  (if present, uploaded to usercontent/)
   Compiler (DataManager)
        ↓  (validation, data transformation, F: directive resolution)
   checklist.json
        ↓  (compressed, placed at usercontent/data/checklist.json)
   Live app reads and displays

Accessing the manage screen

Open the Side Menu (☰ hamburger button) and tap Manage.

Step 1: Upload

Provide your spreadsheet using any of these methods:

• Drag and drop onto the dropzone.
• Browse for a local file.
• Load from URL - switch to the Load from URL tab and paste a publicly accessible direct-download link to your .xlsx file (e.g. a Google Sheets export URL, a Dropbox direct link, or any URL that resolves to a raw xlsx file). This is convenient when your master spreadsheet lives in cloud storage and you want to publish an update without first downloading it to your computer.

The project data must be a .xlsx file; other spreadsheet formats are not currently supported.

Google Sheets

Google Sheets documents hosted as native .gsheet files cannot be loaded directly. Use File → Download → Microsoft Excel (.xlsx) to export, or share a direct download link to the XLSX version from Google Drive.

PHP hosting required for reliable URL loading

Fetching an external file from a browser is subject to CORS (Cross-Origin Resource Sharing) restrictions enforced by the browser. On PHP-enabled hosting, NaturaList routes the request through a server-side proxy, which bypasses browser CORS entirely and works reliably with any publicly accessible URL. On static hosting (GitHub Pages, Netlify, Cloudflare Pages, etc.) there is no server-side proxy available, so the browser must fetch the file directly. Whether this succeeds depends entirely on the CORS policy of the server hosting the spreadsheet - NaturaList has no control over it. Google Sheets export URLs, for instance, do not typically send CORS headers that permit cross-origin fetches, so they will fail on static hosting. The app displays a notice when it detects it is running on static hosting and you attempt to use the URL loader, but it does allow you to try - some self-hosted file servers are configured to allow cross-origin requests and will work fine.

There is a checkbox Check assets size that controls whether the compiler makes HEAD requests to all referenced media files during compilation to verify they exist and check their sizes. This is on by default and strongly recommended - it catches missing files before you publish. Uncheck it only if your update to the spreadsheet did not touch any media files.

Step 2: Processing

The compiler parses the spreadsheet, validates the structure, resolves F: directives (fetching the .md files from the server at compile time), checks asset sizes, and compiles the checklist.json. A spinner is shown during this step. This may take several seconds for large datasets.

Step 3: Review

A summary of compilation messages is shown:

• Errors (red) - block publication. You must fix these in the spreadsheet and re-upload before you can publish.
• Warnings (amber) - do not block publication but indicate content that will not display as intended.

At this stage the compiled data is also loaded into the app as a draft - a yellow banner appears at the top of the screen. Navigate back to the checklist view to browse and verify your data before committing. This draft is stored only in the current browser session and does not affect other users.

Step 4: Publish

Two options depending on your hosting:

• Server Upload (PHP hosts only): if your server has the update.php endpoint configured, enter your credentials and publish directly from the browser. The compiled checklist.json is POSTed to the server and placed in usercontent/data/.

• Download: if you are on static hosting (GitHub Pages, Netlify, etc.), use the Download button to download checklist.json and upload it to usercontent/data/ on your server manually.

Enabling server-side publish

Server-side publishing is configured during installation by setting up credentials.php in usercontent/identity/. If you skipped that step or need to add credentials later, see Installation for the full setup instructions and security notes.

Automatic update detection

Once a project is live, the app uses a stale-while-revalidate strategy for checklist.json: on first load the app waits for the network; on subsequent visits the cached version is served immediately while the server is checked in the background. If Last-Modified or ETag HTTP headers indicate a change, the new version is fetched and users are prompted via a toast notification to reload. If the server provides neither header, the app falls back to re-fetching every 3 days.

After publishing, users who already have the app open or cached may not see the update immediately - they will be prompted to reload when the background check completes.