Page Storage Guide

Understanding where and how pages are stored in GeoHazardWatch.

Overview

GeoHazardWatch uses two directories for page storage, determined by the system-category field in page metadata:

• data/pages/ - User-generated content (default)
• required-pages/ - System and documentation pages

How Storage Routing Works

When you save a page, the system:

1. Reads the system-category from page metadata
2. Looks up the category's storageLocation in configuration
3. Routes the page to the appropriate directory

---
title: My Page
system-category: documentation  # Determines storage location
uuid: abc123-...
---

Storage Categories

required-pages/ Directory

Categories with storageLocation: "required":

Characteristics:

• Protected from accidental deletion
• Higher backup priority
• May be updated during system upgrades

data/pages/ Directory

Categories with storageLocation: "regular":

Characteristics:

• Standard user access
• Can be freely edited/deleted
• Default category for new pages

docs/ Directory (GitHub Only)

Categories with storageLocation: "github":

These pages exist only in the GitHub repository's docs/ folder and cannot be created through the platform interface.

System Initialization

On first run:

1. System copies required-pages/ contents to data/pages/
2. Pages become available on the platform
3. Installation is marked complete

On existing systems:

• required-pages/ serves as the source repository
• System upgrades may update required-pages/
• Administrators can choose to sync updates to data/pages/

Why Two Directories?

Security

• Protect critical system pages from accidental changes
• Apply different permission levels per category

Upgrade Strategy

• required-pages/ contains the canonical system pages
• Upgrades update required-pages/ without affecting user modifications in data/pages/

Organization

• Clear separation of system vs user content
• Easier administration and backup management

Page Metadata

Every page needs proper Frontmatter metadata:

---
title: Page Title                          # Required
uuid: 7682c617-555f-4322-9820-c8ae5a89ca37 # Auto-generated
system-category: documentation             # Determines storage
user-keywords:                             # Searchable tags
  - keyword1
  - keyword2
slug: page-title                           # URL-friendly name
author: Your Name                          # Page creator
lastModified: '2025-10-16T20:05:00.000Z'   # Auto-updated
---

# Page Content Here

Key Fields

Examples

Creating a Documentation Page

---
title: User Guide
system-category: documentation
user-keywords:
  - documentation
  - guide
author: Technical Writer
---

# User Guide

Official documentation content...

Result: Saved to required-pages/[uuid].md

Creating a Regular Page

---
title: My Project Notes
system-category: general
user-keywords:
  - project
  - notes
author: john.doe
---

# My Project Notes

Personal notes and documentation...

Result: Saved to data/pages/[uuid].md

Moving Pages Between Directories

To move a page to a different directory:

1. Edit the page on the platform
2. Change the system-category field
3. Save the page
4. System automatically moves it to the correct directory

Example: Promote page to documentation

# Before (in data/pages/)
system-category: general

# After (in required-pages/)
system-category: documentation

Common Questions

Q: Can I manually move page files?

A: No. Always change the system-category and let the system handle routing.

Q: What happens if I use an invalid category name?

A: Page will use the default category (general) and save to data/pages/.

Q: Why are filenames UUIDs?

A: UUIDs provide:

• Uniqueness (no conflicts)
• Stability (renaming pages doesn't break links)
• Security (harder to guess file locations)
• Works with any language/character set

Q: How do I find a page file on disk?

A: View the page and check the "More Information" section to see its UUID, then look for [uuid].md in the appropriate directory.

Configuration

Storage locations are configured in config/app-default-config.json:

{
  "ngdpbase.system-category": {
    "documentation": {
      "label": "documentation",
      "description": "End-User documentation",
      "storageLocation": "required",
      "enabled": true
    },
    "system": {
      "label": "system",
      "description": "System configuration and infrastructure pages",
      "storageLocation": "required",
      "enabled": true
    },
    "general": {
      "label": "general",
      "description": "General pages",
      "storageLocation": "regular",
      "default": true,
      "enabled": true
    }
  }
}

Troubleshooting

Page not appearing after save

• Check category name is spelled correctly
• Check category is enabled in configuration
• Restart server with ./server.sh restart

Page in wrong directory

• Check category configuration has correct storageLocation
• Edit page and re-save to trigger re-routing

Cannot delete page

• Page may be in required-pages/ and requires admin access
• Change category to general, save, then delete

Best Practices

Do:

• Always include complete metadata
• Use appropriate category for content type
• Choose descriptive titles and keywords
• Let system handle file routing

Don't:

• Manually move files between directories
• Use invalid category names
• Skip Frontmatter metadata
• Rename files directly on filesystem

File Structure

ngdpbase/
├── data/
│   └── pages/                          # User-generated content
│       ├── 1a2b3c4d-5e6f-7890-abcd.md  # General article
│       └── 2b3c4d5e-6f78-90ab-cdef.md  # User notes
│
└── required-pages/                      # System & documentation
    ├── 110fc9ee-90ca-4e6d-b6fa.md      # LeftMenu (system)
    ├── 443c95f1-0b21-494a-b712.md      # FootnoteExample (docs)
    └── 7682c617-555f-4322-9820.md      # This page (docs)

See Page Metadata Documentation for metadata field details, system-category for category configuration, and Frontmatter for the page metadata format.