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.

Step 1: Provide your spreadsheet

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

The project data must be in Excel (.xlsx file) or Google Sheets format (shared via a link with conversion to xlsx).

From a local file

If your spreadsheet is on your computer, provide it by dragging and dropping it onto the dropzone, or by clicking Browse to select it from your file system.

From cloud storage or a URL

Switch to the Load from URL tab and paste a shared link to your spreadsheet. This is the natural workflow for collaborative projects: contributors edit the master spreadsheet in a shared location, and whoever publishes simply loads it straight from there - no download step in between. The URL is used exclusively to fetch the file at compile time; it is never embedded in checklist.json or exposed to the end users of your checklist.

Any URL that delivers a raw xlsx file will work - cloud storage, GitHub or GitLab raw file links, S3-compatible storage, institutional file servers, or any self-hosted location. The only requirement is that the URL resolves directly to the file rather than redirecting through a login page or a browser-based preview.

Using Google Drive or Dropbox

Standard sharing links from both platforms open a preview page rather than delivering the file. The app detects this automatically and offers a one-click conversion.

• Google Drive / Google Sheets: share with Anyone with the link (view access is sufficient) and paste the link as-is. The app will rewrite it to a direct XLSX export URL - https://docs.google.com/spreadsheets/d/{FILE_ID}/export?format=xlsx for native Sheets, or https://drive.google.com/uc?export=download&id={FILE_ID} for Drive-hosted Excel files.
• Dropbox: paste the sharing link (ending in ?dl=0) and the app will offer to switch it to ?dl=1 to force a direct download.

PHP hosting required for reliable URL loading

On PHP-enabled hosting, NaturaList routes URL requests through a server-side proxy, bypassing browser CORS restrictions entirely - any publicly accessible URL will work reliably. On static hosting (GitHub Pages, Netlify, Cloudflare Pages, etc.), the browser must fetch the file directly, and whether this succeeds depends entirely on the CORS policy of the server hosting the spreadsheet. Google Sheets export URLs, for instance, will typically fail. The app warns you when it detects static hosting, but still allows you to try - some file servers permit 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.

If you configured your Darwin Core Archive export, it will be accessible at this step.

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.