{"id":9110,"date":"2026-08-25T01:58:43","date_gmt":"2026-08-25T01:58:43","guid":{"rendered":"https:\/\/metaphaze.com\/gazettebuilder\/?page_id=9110"},"modified":"2026-08-25T01:58:43","modified_gmt":"2026-08-25T01:58:43","slug":"documentation-zip-import","status":"publish","type":"page","link":"https:\/\/metaphaze.com\/gazettebuilder\/documentation-zip-import\/","title":{"rendered":"Documentation: ZIP Import"},"content":{"rendered":"\n

Gazette Builder can import batches of Entries from a ZIP package containing Markdown files and optional media.<\/p>\n\n\n\n

Open:<\/p>\n\n\n\n

GazetteBuilder \u2192 Import<\/strong><\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

A package can carry the Entry article itself together with its GazetteBuilder metadata, semantic references, relationships, Story information, dates, and images.<\/p>\n\n\n\n

This is useful when worldbuilding material is prepared outside WordPress or when a large number of related Entries need to be added together.<\/p>\n\n\n\n

Before Building an Import Package<\/h2>\n\n\n\n

Before importing, configure the Gazette to recognize the classifications and relationships used by the package.<\/p>\n\n\n\n

In particular:<\/p>\n\n\n\n

    \n
  1. Create any required Entry Types<\/strong> under GazetteBuilder \u2192 Entry Types<\/strong>.<\/li>\n\n\n\n
  2. Create any required Relationship Definitions<\/strong> under GazetteBuilder \u2192 Relationship Definitions<\/strong>.<\/li>\n\n\n\n
  3. Make sure Relationship Names in the package use the same canonical names defined in GazetteBuilder.<\/li>\n<\/ol>\n\n\n\n

    For example, if an imported Entry contains:<\/p>\n\n\n\n

    Located in: Syrtis Major<\/pre>\n\n\n\n
    then Located in<\/code> should already be defined as a Relationship Definition with appropriate Source and Target Entry Types.<\/p>\n\n\n\n
    The import package should describe the Entries. It should not be relied upon to create the Gazette’s relationship vocabulary.<\/p>\n\n\n\n
    Package Structure<\/h2>\n\n\n\n
    A Gazette Builder ZIP package uses an entries<\/code> directory for Markdown Entry files and may include a media<\/code> directory for images.<\/p>\n\n\n\n
    A typical package looks like:<\/p>\n\n\n\n
    gazette-package\/
        manifest.yml
        entries\/
            LOC-SYRTIS-MAJOR.md
            LOC-DORCHESTER-HOTEL.md
            CHAR-MAJOR-HARCOURT.md
        media\/
            syrtis-major-map.jpg
            dorchester-hotel.jpg<\/pre>\n\n\n\n
    The importer looks for Markdown files under:<\/p>\n\n\n\n
    entries\/<\/pre>\n\n\n\n
    and media files under:<\/p>\n\n\n\n
    media\/<\/pre>\n\n\n\n
    Subdirectories within media<\/code> may also be used.<\/p>\n\n\n\n
    The current importer does not require the manifest.yml<\/code> to create the Entries; the Entry Markdown files contain the information used for the actual import. A manifest may still be included to identify or describe the package.<\/p>\n\n\n\n
    One Markdown File Per Entry<\/h2>\n\n\n\n
    Each Entry is stored as a .md<\/code> file.<\/p>\n\n\n\n
    The file has two parts:<\/p>\n\n\n\n
      \n
    1. YAML-style front matter<\/strong> containing Gazette Builder metadata.<\/li>\n\n\n\n
    2. The Entry article<\/strong> written below it.<\/li>\n<\/ol>\n\n\n\n
      For example:<\/p>\n\n\n\n
      ---
      id: LOC-DORCHESTER-HOTEL
      title: Dorchester Hotel
      entry_kind: location
      summary: A respectable hotel used by visitors and expedition parties in Syrtis Major.
      featured_media: media\/dorchester-hotel.jpg
      relationships:  
      - \"Located in: Syrtis Major\"  
      - \"In District: Hotel District\"
      ---
      The [[Dorchester Hotel]] is one of the principal colonial hotelsin [[Syrtis Major]].<\/pre>\n\n\n\n
      The opening and closing lines containing three hyphens separate the metadata from the Entry article:<\/p>\n\n\n\n
      ---
      metadata here
      ---
      article begins here<\/pre>\n\n\n\n
      Required Front Matter<\/h2>\n\n\n\n
      Each imported Entry requires:<\/p>\n\n\n\n
      id:
      title:
      entry_kind:<\/pre>\n\n\n\n
      The Entry must also contain article content.<\/p>\n\n\n\n
      A minimal Entry therefore looks like:<\/p>\n\n\n\n
      ---
      id: LOC-SYRTIS-MAJOR
      title: Syrtis Major
      entry_kind: location
      ---
      Syrtis Major is a major Martian canal city.<\/pre>\n\n\n\n
      id<\/code><\/h3>\n\n\n\n
      The stable GazetteBuilder Entry ID.<\/p>\n\n\n\n
      id: LOC-SYRTIS-MAJOR<\/pre>\n\n\n\n
      IDs must be unique.<\/p>\n\n\n\n
      If the ZIP contains the same Entry ID more than once, validation stops the import.<\/p>\n\n\n\n
      An Entry ID that already exists in GazetteBuilder also prevents the package from being imported as a new Entry.<\/p>\n\n\n\n
      title<\/code><\/h3>\n\n\n\n
      The reader-facing Entry title.<\/p>\n\n\n\n
      title: Syrtis Major<\/pre>\n\n\n\n
      Titles containing punctuation can be quoted:<\/p>\n\n\n\n
      title: \"EXP-01: Syrtis Major\"<\/pre>\n\n\n\n
      entry_kind<\/code><\/h3>\n\n\n\n
      The Entry Type slug.<\/p>\n\n\n\n
      entry_kind: location<\/pre>\n\n\n\n
      Use the Entry Type already configured in Gazette Builder.<\/p>\n\n\n\n
      Typical values might include:<\/p>\n\n\n\n
      location
      character
      organization
      document
      event<\/pre>\n\n\n\n
      but the actual valid types are determined by the Entry Types configured on the site.<\/p>\n\n\n\n
      Optional Entry Metadata<\/h2>\n\n\n\n
      The importer can also accept Gazette Builder metadata used by the Entry editor.<\/p>\n\n\n\n
      summary<\/code><\/h3>\n\n\n\n
      A short Entry summary.<\/p>\n\n\n\n
      summary: A major Martian canal city and the principal urban center of the British colony.<\/pre>\n\n\n\n
      campaign_date<\/code><\/h3>\n\n\n\n
      The reader-facing date or date description.<\/p>\n\n\n\n
      campaign_date: \"10 January 1889\"<\/pre>\n\n\n\n
      Campaign Date is descriptive and is separate from the machine-sortable Timeline Sort value.<\/p>\n\n\n\n
      timeline_sort<\/code><\/h3>\n\n\n\n
      A sortable date\/time used for chronological placement.<\/p>\n\n\n\n
      timeline_sort: \"1889-01-10T09:00:00\"<\/pre>\n\n\n\n
      The value must be recognizable as a valid date\/time value.<\/p>\n\n\n\n
      derived_from<\/code><\/h3>\n\n\n\n
      Identifies another Entry from which this Entry is derived.<\/p>\n\n\n\n
      derived_from: LOC-SYRTIS-MAJOR<\/pre>\n\n\n\n
      release_date<\/code><\/h3>\n\n\n\n
      Sets GazetteBuilder’s Release Date.<\/p>\n\n\n\n
      release_date: \"2026-09-01T08:00:00-04:00\"<\/pre>\n\n\n\n
      A future Release Date keeps an otherwise published Entry unavailable until that date is reached.<\/p>\n\n\n\n
      Leaving the field out or empty creates the normal undated-release behavior described in the Publication & Release<\/strong> documentation.<\/p>\n\n\n\n
      status<\/code><\/h3>\n\n\n\n
      Controls the WordPress publication state of the imported Entry.<\/p>\n\n\n\n
      For example:<\/p>\n\n\n\n
      status: publish<\/pre>\n\n\n\n
      If no status is supplied, the current importer defaults imported Entries to:<\/p>\n\n\n\n
      publish<\/pre>\n\n\n\n
      Supported WordPress statuses in the current importer are:<\/p>\n\n\n\n
      publish
      draft
      pending
      private<\/pre>\n\n\n\n
      Story Metadata<\/h2>\n\n\n\n
      Entries can be imported directly into a Story sequence.<\/p>\n\n\n\n
      For example:<\/p>\n\n\n\n
      story_id: EXP-01
      sequence_position: 3<\/pre>\n\n\n\n
      All Entries belonging to the same Story use the same story_id<\/code>.<\/p>\n\n\n\n
      Each must have its own sequence position.<\/p>\n\n\n\n
      The Story landing Entry uses:<\/p>\n\n\n\n
      sequence_position: 0<\/pre>\n\n\n\n
      If an imported Story has no position 0<\/code>, validation reports a blocking error.<\/p>\n\n\n\n
      Duplicate positions within the same Story are also blocking errors.<\/p>\n\n\n\n
      Story landing Entries may also carry the Story display fields supported by Gazette Builder, including:<\/p>\n\n\n\n
      unit_label:
      completion_mode:
      continuing_text:
      ending_text:<\/pre>\n\n\n\n
      Story configuration is covered separately under Stories<\/strong>.<\/p>\n\n\n\n
      Semantic References in the Article<\/h2>\n\n\n\n
      Semantic references use exactly the same syntax in imported Markdown as they do in the WordPress Entry editor:<\/p>\n\n\n\n
      [[Target Entry]]<\/pre>\n\n\n\n
      For example:<\/p>\n\n\n\n
      The expedition established itself in [[Syrtis Major]]and took rooms at the [[Dorchester Hotel]].<\/pre>\n\n\n\n
      Do not convert these into Markdown hyperlinks.<\/p>\n\n\n\n
      Gazette Builder needs the semantic markup itself:<\/p>\n\n\n\n
      [[Syrtis Major]]<\/pre>\n\n\n\n
      rather than:<\/p>\n\n\n\n
      [Syrtis Major](some-wordpress-url)<\/pre>\n\n\n\n
      During Preview \/ Validate, Gazette Builder examines semantic references and reports whether they currently resolve.<\/p>\n\n\n\n
      An unresolved semantic reference is not necessarily an error.<\/p>\n\n\n\n
      For example:<\/p>\n\n\n\n
      [[Hobo Club]]<\/pre>\n\n\n\n
      may deliberately refer to an Entry that will be created later.<\/p>\n\n\n\n
      The preview reports such references as warnings rather than blocking the entire package.<\/p>\n\n\n\n
      Relationships<\/h2>\n\n\n\n
      Relationships are declared in front matter as a list:<\/p>\n\n\n\n
      relationships:
        - \"Located in: Syrtis Major\"
        - \"In District: Residency\"
        - \"On Street: Bedford Road\"<\/pre>\n\n\n\n
      Use one relationship per list item.<\/p>\n\n\n\n
      Each item follows the same format used in the Entry editor:<\/p>\n\n\n\n
      Relationship Name: Target Entry<\/pre>\n\n\n\n
      The text before the colon must use the canonical Name<\/strong> configured in Gazette Builder’s Relationship Definitions.<\/p>\n\n\n\n
      The text after the colon is the target Entry.<\/p>\n\n\n\n
      Define Relationships Before Importing<\/h3>\n\n\n\n
      Relationship Definitions should already exist before importing Entries that use them.<\/p>\n\n\n\n
      For example, before importing:<\/p>\n\n\n\n
      relationships:
        - \"In District: Residency\"<\/pre>\n\n\n\n
      GazetteBuilder should already contain a Relationship Definition whose Name is:<\/p>\n\n\n\n
      In District<\/pre>\n\n\n\n
      with suitable Source and Target Entry Types.<\/p>\n\n\n\n
      This keeps the import package and the Gazette’s controlled relationship vocabulary synchronized.<\/p>\n\n\n\n
      The Import Preview reports the relationship declarations it discovers so they can be inspected before the package is committed.<\/p>\n\n\n\n
      Featured Media<\/h2>\n\n\n\n
      A Featured Image can be supplied through the featured_media<\/code> field.<\/p>\n\n\n\n
      For example:<\/p>\n\n\n\n
      featured_media: media\/dorchester-hotel.jpg<\/pre>\n\n\n\n
      The referenced file must exist inside the ZIP’s media<\/code> directory:<\/p>\n\n\n\n
      media\/
          dorchester-hotel.jpg<\/pre>\n\n\n\n
      During import, Gazette Builder transfers the file into the normal WordPress Media Library and assigns the resulting WordPress attachment as the Entry’s Featured Image.<\/p>\n\n\n\n
      The package path is therefore only an import-time reference.<\/p>\n\n\n\n
      The Entry does not continue depending on:<\/p>\n\n\n\n
      media\/dorchester-hotel.jpg<\/pre>\n\n\n\n
      after import. WordPress takes ownership of the imported media file.<\/p>\n\n\n\n
      Inline Images<\/h2>\n\n\n\n
      Images can also appear inside the Entry article using normal Markdown image syntax:<\/p>\n\n\n\n
      ![Description](media\/syrtis-major-map.jpg)<\/pre>\n\n\n\n
      For example:<\/p>\n\n\n\n
      The city's principal canal intersections are shown below.![Map of Syrtis Major](media\/syrtis-major-map.jpg)<\/pre>\n\n\n\n
      The corresponding package structure is:<\/p>\n\n\n\n
      media\/
          syrtis-major-map.jpg<\/pre>\n\n\n\n
      Gazette Builder locates that image in the package, imports it into the WordPress Media Library, and replaces the package reference with the imported WordPress media URL in the Entry.<\/p>\n\n\n\n
      Image Text<\/h2>\n\n\n\n
      The text inside the square brackets is used by the importer for the image’s descriptive text.<\/p>\n\n\n\n
      For example:<\/p>\n\n\n\n
      ![Test map of Syrtis Major](media\/syrtis-major-map.jpg)<\/pre>\n\n\n\n
      produces an imported image using:<\/p>\n\n\n\n
      Test map of Syrtis Major<\/pre>\n\n\n\n
      as the image text and also presents that text as the figure caption.<\/p>\n\n\n\n
      If the square brackets are empty:<\/p>\n\n\n\n
      ![](media\/syrtis-major-map.jpg)<\/pre>\n\n\n\n
      no caption is generated.<\/p>\n\n\n\n
      Media Paths<\/h2>\n\n\n\n
      The clearest form is to use the full package-relative path:<\/p>\n\n\n\n
      media\/syrtis-major-map.jpg<\/pre>\n\n\n\n
      Gazette Builder normalizes media references and can also match an unambiguous file by filename, but using the complete media\/...<\/code> path is preferable because it makes the package explicit and avoids ambiguity.<\/p>\n\n\n\n
      Do not use external URLs as package media references.<\/p>\n\n\n\n
      Do not use paths that attempt to move outside the package, such as:<\/p>\n\n\n\n
      ..\/images\/map.jpg<\/pre>\n\n\n\n
      Using the Same Image More Than Once<\/h2>\n\n\n\n
      The same packaged media file can be referenced by more than one Entry or used as both Featured Media and inline content.<\/p>\n\n\n\n
      Gazette Builder maintains an import-time media cache so the same package asset can be reused rather than imported as a separate WordPress attachment every time it is encountered.<\/p>\n\n\n\n
      Missing Images Are Blocking Errors<\/h2>\n\n\n\n
      Every referenced package image must actually be present.<\/p>\n\n\n\n
      If an Entry contains:<\/p>\n\n\n\n
      featured_media:
       media\/missing-map.jpg<\/pre>\n\n\n\n
      or:<\/p>\n\n\n\n
      ![Map](media\/missing-map.jpg)<\/pre>\n\n\n\n
      and that file is not found in the ZIP, Preview \/ Validate reports the missing media as a blocking error.<\/p>\n\n\n\n
      The package must be corrected before import.<\/p>\n\n\n\n
      Complete Example<\/h2>\n\n\n\n
      A Location Entry using most of the common import features might look like:<\/p>\n\n\n\n
      ---
      id: LOC-DORCHESTER-HOTEL
      title: Dorchester Hotel
      entry_kind: location
      summary: A respectable colonial hotel used by visitors and expedition parties in Syrtis Major.
      campaign_date: \"January 1889\"
      timeline_sort: \"1889-01-01T00:00:00\"
      release_date: \"2026-08-24T20:00:00-04:00\"
      status: publish
      featured_media: media\/dorchester-hotel.jpg
      relationships:
        - \"Located in: Syrtis Major\"
        - \"In District: Hotel District\"
      ---
      The [[Dorchester Hotel]] serves travelers arriving in[[Syrtis Major]].![Dorchester Hotel](media\/dorchester-hotel.jpg)<\/pre>\n\n\n\n
      Its ZIP contains:<\/p>\n\n\n\n
      entries\/
          LOC-DORCHESTER-HOTEL.md
      media\/
          dorchester-hotel.jpg<\/pre>\n\n\n\n
      Before importing it, GazetteBuilder should already have:<\/p>\n\n\n\n
      Entry Type:Location
      Relationship Definitions:
      Located in
      In District<\/pre>\n\n\n\n
      Preview \/ Validate<\/h2>\n\n\n\n
      To inspect a package:<\/p>\n\n\n\n
        \n
      1. Open GazetteBuilder \u2192 Import<\/strong>.<\/li>\n\n\n\n
      2. Select the ZIP file.<\/li>\n\n\n\n
      3. Select Preview \/ Validate<\/strong>.<\/li>\n<\/ol>\n\n\n\n
        Gazette Builder examines the package without creating the Entries.<\/p>\n\n\n\n
        The current preview reports information including:<\/p>\n\n\n\n
          \n
        • number of Entries discovered;<\/li>\n\n\n\n
        • new Entries;<\/li>\n\n\n\n
        • duplicate Entry IDs;<\/li>\n\n\n\n
        • Entry IDs that already exist;<\/li>\n\n\n\n
        • missing required metadata;<\/li>\n\n\n\n
        • Entry validation errors;<\/li>\n\n\n\n
        • Story membership;<\/li>\n\n\n\n
        • missing Story position 0<\/code>;<\/li>\n\n\n\n
        • duplicate Story positions;<\/li>\n\n\n\n
        • missing media;<\/li>\n\n\n\n
        • semantic references that resolve;<\/li>\n\n\n\n
        • unresolved semantic references;<\/li>\n\n\n\n
        • ambiguous semantic references;<\/li>\n\n\n\n
        • relationship declarations discovered;<\/li>\n\n\n\n
        • blocking errors;<\/li>\n\n\n\n
        • warnings.<\/li>\n<\/ul>\n\n\n\n
          Blocking Errors and Warnings<\/h2>\n\n\n\n
          A blocking error<\/strong> prevents the package from being imported.<\/p>\n\n\n\n
          Examples include:<\/p>\n\n\n\n
            \n
          • missing id<\/code>, title<\/code>, or entry_kind<\/code>;<\/li>\n\n\n\n
          • duplicate Entry IDs;<\/li>\n\n\n\n
          • an Entry ID that already exists;<\/li>\n\n\n\n
          • invalid required Story structure;<\/li>\n\n\n\n
          • duplicate Story sequence positions;<\/li>\n\n\n\n
          • invalid Release Date or Timeline Sort values;<\/li>\n\n\n\n
          • missing referenced media.<\/li>\n<\/ul>\n\n\n\n
            A warning<\/strong> does not necessarily make the package invalid.<\/p>\n\n\n\n
            The most common example is an unresolved semantic reference to an Entry that has not yet been created.<\/p>\n\n\n\n
            Commit the Import<\/h2>\n\n\n\n
            If Preview \/ Validate finds no blocking errors, GazetteBuilder displays the Import Entries<\/strong> step.<\/p>\n\n\n\n
            The current interface requires the validated ZIP file to be selected again before committing the import.<\/p>\n\n\n\n
            After re-selecting the package:<\/p>\n\n\n\n
              \n
            1. Select Import Entries<\/strong>.<\/li>\n\n\n\n
            2. Gazette Builder creates the Entries.<\/li>\n\n\n\n
            3. Referenced media is imported into the WordPress Media Library.<\/li>\n\n\n\n
            4. Inline image references are rewritten to the imported WordPress media.<\/li>\n\n\n\n
            5. Featured Media is assigned.<\/li>\n\n\n\n
            6. Entry metadata, Story data, semantic markup, and relationships are retained.<\/li>\n<\/ol>\n\n\n\n
              If an error occurs while creating the package, GazetteBuilder attempts to roll back Entries and media already created by that import rather than intentionally leaving a partial package behind.<\/p>\n\n\n\n
              A Good Import Workflow<\/h2>\n\n\n\n
              For a larger import, the safest order is:<\/p>\n\n\n\n
                \n
              1. Create the required Entry Types.<\/li>\n\n\n\n
              2. Create the required Relationship Definitions.<\/li>\n\n\n\n
              3. Build the Markdown Entry files.<\/li>\n\n\n\n
              4. Add semantic references to the article text.<\/li>\n\n\n\n
              5. Add relationship declarations to front matter.<\/li>\n\n\n\n
              6. Add Story and chronology metadata where needed.<\/li>\n\n\n\n
              7. Place all referenced images in media\/<\/code>.<\/li>\n\n\n\n
              8. ZIP the package.<\/li>\n\n\n\n
              9. Run Preview \/ Validate<\/strong>.<\/li>\n\n\n\n
              10. Correct all blocking errors and review warnings.<\/li>\n\n\n\n
              11. Re-run Preview \/ Validate until the package is clean.<\/li>\n\n\n\n
              12. Commit the import.<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"
                Gazette Builder can import batches of Entries from a ZIP package containing Markdown files and optional media. Open: GazetteBuilder \u2192 Import A package can carry the Entry article itself together with its GazetteBuilder metadata, semantic references, relationships, Story information, dates, and images. This is useful when worldbuilding material is prepared outside WordPress or when a […]<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-9110","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/pages\/9110","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/comments?post=9110"}],"version-history":[{"count":1,"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/pages\/9110\/revisions"}],"predecessor-version":[{"id":9112,"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/pages\/9110\/revisions\/9112"}],"wp:attachment":[{"href":"https:\/\/metaphaze.com\/gazettebuilder\/wp-json\/wp\/v2\/media?parent=9110"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}