Workspace Config

When designing OpenPress’s configuration system, we faced a common dilemma: how to maintain flexibility in configuration without creating a massive, complex, and unmaintainable global config file?

To solve this problem, OpenPress adopts a dual strategy of “separation of concerns” and “convention over configuration.” We explicitly divide the workspace configuration into three distinct areas.

1. Document Metadata: Belongs to Components

Attributes regarding the document itself — such as what kind of document it is, its title, its paper geometry size — are designed to be attached to the specific Press component.

Why design it this way? Because within a single workspace, there might be multiple different publications simultaneously (e.g., a portrait proposal report and a landscape presentation deck). If this information was placed in a global configuration, it would quickly become difficult to differentiate and manage. By making metadata the props of React components, we ensure that the configuration always closely follows the object it describes, achieving perfect encapsulation.

2. Operations Settings: Belongs to Project Configuration

Some settings have nothing to do with the content of the document, but rather with “how the workspace operates”, for example: which hosting platform will this document eventually be deployed to? What specific platform parameters are needed during deployment?

These operational-level settings are placed in standard project configuration files (like package.json).

Why design it this way? This type of setting is usually set only once during the project’s lifecycle. More importantly, external systems like deployment scripts or Continuous Integration (CI) tools need to be able to quickly read these environment details without executing any React code or compiling documents. Placing them in standard configuration files ensures seamless integration with external toolchains.

3. Directory Structure: Convention Over Configuration

Regarding where files should be placed (e.g., where are the theme styles? Where are the shared components? Where does the compiled output go?), OpenPress deliberately provides little room for customization, opting instead for fixed path conventions.

Why design it this way? While this seems to reduce freedom, it brings massive benefits. When all OpenPress projects follow the same file structure, AI Agents know exactly where to look for resources or write files without any extra guidance. This standardization also greatly reduces the cognitive load for human authors when switching between different projects. These path conventions are not knobs that can be tweaked at will, but are a part of the core product architecture.