Skip to content

File Structure & Organization

Understanding the project directory layout is essential before making any changes. Every file has a specific location, and moving or renaming files without updating references will break the site.

Project Directory Layout

The EPMware Administrator's Guide follows this structure:

epmware-admin-guide/
├── mkdocs.yml                          # Site configuration
├── docs/
│   ├── index.md                        # Home page
│   ├── assets/
│   │   ├── css/
│   │   │   └── custom.css              # Custom styling
│   │   └── images/
│   │       ├── epmware-logo.png        # Site logo
│   │       ├── favicon.ico             # Browser tab icon
│   │       ├── configuration/          # Configuration section images
│   │       ├── security/               # Security section images
│   │       ├── workflow/               # Workflow section images
│   │       ├── deployment/             # Deployment section images
│   │       ├── export/                 # Export section images
│   │       ├── logic-builder/          # Logic Builder section images
│   │       ├── administration/         # Administration section images
│   │       └── appendices/             # Appendices section images
│   ├── configuration/
│   │   ├── index.md                    # Configuration overview
│   │   ├── infrastructure.md
│   │   ├── applications.md
│   │   ├── dimensions.md
│   │   ├── member-properties.md
│   │   ├── email-templates.md
│   │   ├── global-settings.md
│   │   └── lookups.md
│   ├── security/
│   │   └── index.md
│   ├── workflow/
│   │   └── index.md
│   ├── deployment/
│   │   └── index.md
│   ├── export/
│   │   └── index.md
│   ├── logic-builder/
│   │   └── index.md
│   ├── administration/
│   │   ├── index.md
│   │   ├── migration.md
│   │   └── erp-import.md
│   └── appendices/
│       ├── index.md
│       ├── oracle-epm-cloud.md
│       ├── oracle-fusion-gl.md
│       ├── validations.md
│       ├── onestream.md
│       └── oracle-ebs-gl.md
└── .github/
    └── workflows/
        └── deploy.yml                  # GitHub Actions deployment

Key Directories

docs/

All markdown content lives under docs/. This is the root directory that MkDocs processes. When MkDocs builds the site, it converts each .md file into an HTML page and organizes them according to the nav section in mkdocs.yml.

docs/assets/

Static files like CSS, images, and the site logo live here. These are copied directly to the built site without processing.

Section Folders (configuration/, security/, etc.)

Each major section of the guide has its own folder. Sections with a single page use an index.md file inside the folder. Sections with multiple pages (like configuration/ and administration/) have additional .md files alongside the index.md.

Index Files and Navigation

The navigation.indexes feature in the Material theme means that index.md files serve as the landing page for their parent section in the navigation sidebar. When someone clicks "Configuration" in the nav, they see configuration/index.md.

File Naming Conventions

Follow these conventions when creating or renaming files:

  • Use lowercase for all filenames
  • Use hyphens (-) to separate words, never underscores or spaces (e.g., member-properties.md, not member_properties.md or Member Properties.md)
  • Use descriptive names that match the page title (e.g., the "Email Templates" page should be email-templates.md)
  • Image files should use descriptive names that indicate what the image shows (e.g., dimension-classes-grid.png instead of image43.png)

Renaming Files

If you rename any .md file, you must also update all references to that file in mkdocs.yml navigation entries, all markdown links pointing to that file from other pages, and all HTML <a href> links pointing to that file. Use your editor's search-across-files feature to find all references before renaming.

Adding a New Page

To add a new page to the documentation:

  1. Create the .md file in the appropriate section folder.
  2. Add the file to the nav section in mkdocs.yml.
  3. Add links to the new page from related pages (such as the section's index.md).
  4. Run mkdocs serve to verify the page appears correctly.

See Editing mkdocs.yml for details on updating the navigation.